Core Concepts

Watchers

A Watcher is the core instrumentation primitive. It attaches to your pipeline graph and records everything that happens during execution — node inputs, outputs, state transitions, timing, and tool calls.

The Watcher doesn't modify your pipeline's behavior. It's a passive observer that hooks into execution callbacks. Your pipeline runs exactly as it would without ARGUS — the Watcher just records what happened.

from argus import ArgusWatcher

watcher = ArgusWatcher(graph)      # attaches monitoring automatically
app = graph.compile()
result = app.invoke(initial_state) # run auto-saves when the last node finishes
print(watcher.run_id)              # access the run ID directly

Detection Layers

ARGUS doesn't throw everything at an LLM. Detection runs in four layers, each more expensive than the last, and each only fires when needed:

• 1.Heuristic engine — pattern matching against 150+ known failure signatures (placeholder outputs, empty results, error keys, semantic degradation markers). Deterministic, zero cost, catches ~80% of failures.
• 2.Anomaly detector — statistical checks for suspicious patterns (unexpected field types, output size anomalies, timing outliers). Still deterministic.
• 3.Correlator — traces failure propagation across nodes. If node 3 dropped a field and node 5 crashed because of it, the correlator builds the causal chain and points you at node 3, not node 5.
• 4.LLM investigator — only triggers on ambiguous failures or when explicitly enabled. Generates root cause explanations, causal hypotheses, and debugging suggestions. Also proposes new heuristic signatures so the same failure gets caught deterministically next time.

Traces

A Trace is the complete record of a single pipeline execution. It contains:

• Every node that executed, in order
• Input and output state at each node
• Wall clock timing per step
• Tool calls and their results
• Detection results from all four layers
• Forensic analysis if failures were detected

# View the latest run
argus show last

# View a specific run by ID (or 8-char prefix)
argus show run abc12345

# List all runs
argus list

Runs are stored locally in .argus/runs/ by default. See Storage for details.

Forensics

When detectors flag a failure, the Forensics engine kicks in. It traces the failure backward through the execution graph to find the root cause — which node, which input, which state transition caused the downstream degradation.

Forensic analysis answers three questions:

• ‣What failed? — the specific detection that fired and what it found
• ‣Where did it fail? — the node and step in the execution graph
• ‣Why did it fail? — the causal chain from the root cause to the observed symptom

How They Connect

1. You create a Watcher and attach it to your graph
2. Your pipeline runs normally — the Watcher records a Trace
3. Detectors analyze the trace (auto-runs for linear/fan-out graphs)
4. If failures are found — Forensics traces back to root cause
5. You view results via CLI, UI, or programmatic API