Implement runtime chain observer with auto-flow suggestion

[dgenio]

Context / Problem

Users must manually define flows by inspecting their agent's behavior and hand-wiring steps. The real power of ChainWeaver's "compiled" metaphor is the ability to observe what agents do at runtime, detect repeated deterministic patterns, and suggest compiled flows automatically.

This transforms ChainWeaver from a manual flow-definition library into an intelligent optimization layer: "Your agent called fetch→validate→transform 47 times with the same routing. Would you like to compile this into a flow?"

Proposal

Implement a ChainObserver that records tool call traces, detects repeated sequences, and proposes Flow objects for approval:

from chainweaver import ChainObserver

observer = ChainObserver()

# Record tool calls as they happen (from agent runtime)
observer.record("fetch", {"url": "..."}, {"data": "..."})
observer.record("validate", {"data": "..."}, {"valid": True})
observer.record("transform", {"data": "..."}, {"result": "..."})
observer.end_trace()  # marks end of one tool-call sequence

# ... after many traces ...

# Detect repeated patterns
suggestions = observer.suggest_flows(min_occurrences=3, min_length=2)
# [FlowSuggestion(name="fetch_validate_transform", confidence=0.92, occurrences=47, flow=Flow(...))]

# Approve and register
registry.register_flow(suggestions[0].flow)

Core capabilities:

1. Trace recording — capture tool name, inputs, outputs per call; group into traces (sequences)
2. Pattern detection — find repeated sub-sequences across traces using sequence mining (e.g., longest common subsequences, n-gram analysis)
3. Determinism scoring — for each detected pattern, compute a confidence score: how consistently the same inputs produce the same routing
4. Flow suggestion — generate Flow objects from detected patterns with auto-wired input_mapping
5. Governance gate — suggestions are proposals, NOT auto-registered; human approval required

Acceptance Criteria

• ChainObserver class with record() and end_trace() methods
• Traces are stored in memory (with configurable max buffer size)
• suggest_flows(min_occurrences, min_length) returns FlowSuggestion objects
• FlowSuggestion includes: suggested Flow, occurrence count, confidence score, example trace
• Pattern detection finds repeated 2+ step sequences across 3+ traces
• Confidence score reflects how consistently the pattern appears (0.0–1.0)
• Suggested flows are NOT auto-registered — explicit registry.register_flow() required
• Tests cover: basic detection, no patterns, overlapping patterns, confidence scoring, governance gate

Implementation Notes

• Start with simple n-gram frequency counting on tool-name sequences
• Confidence = occurrences / total traces containing the start tool
• input_mapping auto-generation can reuse logic from Offline computation of valid tool combinations from schemas #77 (ChainAnalyzer)
• Consider integrating with Implement structured execution trace with trace IDs and timing #20 (structured execution traces) for richer trace data
• Future: persist traces to disk for offline analysis

Dependencies

• Offline computation of valid tool combinations from schemas #77 (ChainAnalyzer) — shares schema compatibility logic for auto-wiring
• Add determinism scoring and candidate flow proposal from traces #12, Design opt-in governance workflow for promoting observed chains #13 (existing issues) — this supersedes/encompasses their scope with a full end-to-end design

Tasks

• Create chainweaver/observer.py with ChainObserver class
• Implement trace recording and buffering
• Implement n-gram-based pattern detection
• Implement determinism/confidence scoring
• Implement FlowSuggestion dataclass and suggest_flows() method
• Add governance gate documentation and example
• Add unit tests in tests/test_observer.py
• Add example: examples/chain_observer.py
• Document in README under "Runtime Learning" section

[dgenio]

Cross-reference: related to #11, #12, #13

This issue (#78 — "Runtime event observer — hooks, plugins, trace export") overlaps with three earlier issues:

• Implement runtime chain observation and trace capture #11 ("Capture execution trace per step") — trace capture is a core feature of Implement runtime chain observer with auto-flow suggestion #78's Observer protocol
• Add determinism scoring and candidate flow proposal from traces #12 ("Optional scoring / weighting per step") — could be implemented as an Observer plugin
• Design opt-in governance workflow for promoting observed chains #13 ("Governance & compliance hooks") — before_step / after_step hooks provide the extension points for compliance

When implementing #78, consider absorbing the scope of #11/#12/#13 into Observer plugins, or closing them as superseded if #78's architecture fully covers their requirements.

---

Added during backlog review.