chore(docs): documentation

Author: AKOrojo

Cargo.lock

@@ -330,6 +330,22 @@ packets = rdpcap("capture.pcap")
 conversations = extract_flows_from_packets(packets)
 ```
 
+Enable verbose mode to see progress feedback on stderr during extraction:
+
+```python
+# Quick verbose flag on the function call
+conversations = extract_flows("capture.pcap", verbose=True)
+# [stackforge] Opening capture file: capture.pcap
+# [stackforge] Starting streaming flow extraction...
+# [stackforge] Processed 10000 packets (342 flows so far)
+# [stackforge] Processed 20000 packets (587 flows so far)
+# [stackforge] Flow extraction complete: 612 conversations
+
+# Or via FlowConfig
+config = FlowConfig(verbose=True)
+conversations = extract_flows("capture.pcap", config=config)
+```
+
 Customize timeouts, buffer limits, and memory budget with `FlowConfig`:
 
 ```python

README.md

@@ -30,6 +30,8 @@ pub struct FlowConfig {
     pub memory_budget: Option<usize>,
     /// Directory for spill files (None = system temp dir).
     pub spill_dir: Option<PathBuf>,
+    /// Print progress feedback to stderr during flow extraction (default: false).
+    pub verbose: bool,
 }
 
 impl Default for FlowConfig {
@@ -46,6 +48,7 @@ impl Default for FlowConfig {
             track_max_flow_len: false,
             memory_budget: None,
             spill_dir: None,
+            verbose: false,
         }
     }
 }

crates/stackforge-core/src/.DS_Store

@@ -75,14 +75,35 @@ pub fn extract_flows_with_config(
     packets: &[CapturedPacket],
     config: FlowConfig,
 ) -> Result<Vec<ConversationState>, FlowError> {
+    let verbose = config.verbose;
+    let total = packets.len();
     let table = ConversationTable::new(config);
 
+    if verbose {
+        eprintln!("[stackforge] Starting flow extraction ({total} packets)...");
+    }
+
     for (index, captured) in packets.iter().enumerate() {
         let timestamp = captured.metadata.timestamp;
         table.ingest_packet(&captured.packet, timestamp, index)?;
+
+        if verbose && (index + 1) % 10_000 == 0 {
+            eprintln!(
+                "[stackforge] Processed {}/{total} packets ({} flows so far)",
+                index + 1,
+                table.conversation_count(),
+            );
+        }
     }
 
-    Ok(table.into_conversations())
+    let conversations = table.into_conversations();
+    if verbose {
+        eprintln!(
+            "[stackforge] Flow extraction complete: {total} packets -> {} conversations",
+            conversations.len(),
+        );
+    }
+    Ok(conversations)
 }
 
 /// Extract flows from a streaming packet source (iterator).
@@ -100,16 +121,36 @@ pub fn extract_flows_streaming<I>(
 where
     I: Iterator<Item = Result<CapturedPacket, PacketError>>,
 {
+    let verbose = config.verbose;
     let table = ConversationTable::new(config);
 
+    if verbose {
+        eprintln!("[stackforge] Starting streaming flow extraction...");
+    }
+
     for (index, result) in packets.enumerate() {
         let captured = result.map_err(FlowError::PacketError)?;
         let timestamp = captured.metadata.timestamp;
         table.ingest_packet(&captured.packet, timestamp, index)?;
         // `captured` is dropped here — packet memory freed immediately
+
+        if verbose && (index + 1) % 10_000 == 0 {
+            eprintln!(
+                "[stackforge] Processed {} packets ({} flows so far)",
+                index + 1,
+                table.conversation_count(),
+            );
+        }
     }
 
-    Ok(table.into_conversations())
+    let conversations = table.into_conversations();
+    if verbose {
+        eprintln!(
+            "[stackforge] Flow extraction complete: {} conversations",
+            conversations.len(),
+        );
+    }
+    Ok(conversations)
 }
 
 /// Extract flows directly from a capture file (PCAP or PcapNG).
@@ -120,6 +161,13 @@ pub fn extract_flows_from_file(
     path: impl AsRef<Path>,
     config: FlowConfig,
 ) -> Result<Vec<ConversationState>, FlowError> {
+    let verbose = config.verbose;
+    if verbose {
+        eprintln!(
+            "[stackforge] Opening capture file: {}",
+            path.as_ref().display(),
+        );
+    }
     let iter = CaptureIterator::open(path).map_err(FlowError::PacketError)?;
     extract_flows_streaming(iter, config)
 }

crates/stackforge-core/src/flow/config.rs

@@ -4076,6 +4076,7 @@ impl PyFlowConfig {
         track_max_flow_len=false,
         memory_budget=None,
         spill_dir=None,
+        verbose=false,
     ))]
     #[allow(clippy::too_many_arguments)]
     fn new(
@@ -4089,6 +4090,7 @@ impl PyFlowConfig {
         track_max_flow_len: bool,
         memory_budget: Option<usize>,
         spill_dir: Option<String>,
+        verbose: bool,
     ) -> Self {
         Self {
             inner: stackforge_core::FlowConfig {
@@ -4104,6 +4106,7 @@ impl PyFlowConfig {
                 track_max_flow_len,
                 memory_budget,
                 spill_dir: spill_dir.map(std::path::PathBuf::from),
+                verbose,
                 ..stackforge_core::FlowConfig::default()
             },
         }
@@ -4451,9 +4454,16 @@ impl PyConversation {
 /// Returns:
 ///     List of Conversation objects sorted by start time.
 #[pyfunction]
-#[pyo3(signature = (pcap_path, config=None))]
-fn extract_flows(pcap_path: &str, config: Option<PyFlowConfig>) -> PyResult<Vec<PyConversation>> {
-    let flow_config = config.map(|c| c.inner).unwrap_or_default();
+#[pyo3(signature = (pcap_path, config=None, verbose=false))]
+fn extract_flows(
+    pcap_path: &str,
+    config: Option<PyFlowConfig>,
+    verbose: bool,
+) -> PyResult<Vec<PyConversation>> {
+    let mut flow_config = config.map(|c| c.inner).unwrap_or_default();
+    if verbose {
+        flow_config.verbose = true;
+    }
 
     // Use streaming extraction — never loads all packets into memory at once
     let conversations =
@@ -4484,10 +4494,11 @@ fn extract_flows(pcap_path: &str, config: Option<PyFlowConfig>) -> PyResult<Vec<
 /// Returns:
 ///     List of Conversation objects sorted by start time.
 #[pyfunction]
-#[pyo3(signature = (packets, config=None))]
+#[pyo3(signature = (packets, config=None, verbose=false))]
 fn extract_flows_from_packets(
     packets: Vec<PyRef<'_, PyPacket>>,
     config: Option<PyFlowConfig>,
+    verbose: bool,
 ) -> PyResult<Vec<PyConversation>> {
     let captured: Vec<stackforge_core::CapturedPacket> = packets
         .iter()
@@ -4502,7 +4513,10 @@ fn extract_flows_from_packets(
         })
         .collect();
 
-    let flow_config = config.map(|c| c.inner).unwrap_or_default();
+    let mut flow_config = config.map(|c| c.inner).unwrap_or_default();
+    if verbose {
+        flow_config.verbose = true;
+    }
 
     let conversations = stackforge_core::extract_flows_with_config(&captured, flow_config)
         .map_err(|e| pyo3::exceptions::PyRuntimeError::new_err(format!("{e}")))?;