Parallax

When expectation and observation diverge, reliability is already failing.

Runtime reliability, diagnosis, and recovery for autonomous AI agents.
Research stack: AgentFailBench · Semantic Runtime Monitor · RecoverAI

---

Why Parallax?

In optics, parallax is the apparent shift of an object when viewed from two positions.

In agent systems, the same failure mode appears as a gap between:

Viewpoint	Signal
Expectation	What the agent believed a tool, memory, or plan step meant
Observation	What the environment actually returned

If those viewpoints drift while HTTP still returns 200, classic monitors stay quiet — and the task fails later, with the diagnostic window already closed.

Parallax measures that gap early — then diagnoses and recovers.

Central question

How can an autonomous system detect that it is becoming unreliable before visible task failure, distinguish the root cause, estimate the risk of continuing, and choose a safe recovery strategy?

---

The invisible failure

Tool semantic drift is the first vertical slice: schema stays valid, transport succeeds, meaning changes. The agent acts on the wrong world model — and nothing throws.

AgentFailBench injects that class of failure with ground-truth labels so detectors and recovery policies can be evaluated, not just demoed.

---

Reliability lifecycle

Controlled failure
      ↓
Semantic execution trace
      ↓
Early failure detection
      ↓
Root-cause diagnosis
      ↓
Risk estimation
      ↓
Recovery selection
      ↓
Post-recovery evaluation

---

Reliability stack

Layer	Package	Role
Benchmark	agentfailbench/	Tasks, environments, injectors, ground-truth labels
Monitor	runtime/	Traces, features, detectors, diagnosis, calibration
Recovery	recovery/	Policies, actions, constraints, sandbox evaluation
Baselines	baselines/	Rules, classical ML, sequence models, LLM judges

flowchart TB
  A[Agent task] --> B[Execution layer]
  B --> C[Semantic Trace Collector]
  C --> D[Reliability Intelligence]
  D --> E[Recovery Governor]
  E --> F[Evaluation Layer]
  F -.->|metrics| D

Loading

---

Core contributions

#	Contribution	What you get
1	Failure taxonomy	Model · planning · memory · retrieval · tool · data · environment · communication · execution · recovery
2	AgentFailBench	Controlled degradation with first-detectable / final-failure steps
3	Semantic Runtime Monitor	Goals, beliefs, actions, expectations, observations, state changes
4	RecoverAI	Failure-conditioned recovery vs retry-only / restart / generic reflection

---

Quick start

Requires Python 3.12+.

git clone https://github.com/askmy-stack/parallax.git
cd parallax

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

make install
make test
ras --version

Run the first vertical-slice experiment (tool semantic drift):

ras experiment run --case tool-semantic-drift-001 --compare
# → experiments/results/tool-semantic-drift-001.md

Optional local telemetry UI:

docker compose up -d jaeger
# UI → http://localhost:16686

Inspect the first benchmark case:

cat agentfailbench/failures/tool_drift/tool-semantic-drift-001.yaml

---

Repository map

parallax/
├── agentfailbench/     # benchmark cases + injectors
├── runtime/            # semantic monitor + detectors
├── recovery/           # RecoverAI policies
├── baselines/          # comparison methods
├── experiments/        # configs · notebooks · results
├── docs/               # specs · ADRs · roadmap
│   └── assets/         # README visuals
├── examples/           # minimal agent scaffolds
├── tests/              # unit · integration · benchmark
└── paper/              # technical report scaffold

---

Research status

Milestone	Focus	Status
0	Repository foundation	✅ done
1	Minimal agent environment (customer API slice)	✅ vertical slice
2	Failure injection (semantic drift)	✅ vertical slice
3	Semantic tracing	✅ vertical slice
4–6	Detection · diagnosis · recovery	✅ first-slice baselines
7	Research release v0.1	planned

First experiment results: experiments/results/tool-semantic-drift-001.md

Detector	Detected drift?	Notes
Exception	No	HTTP 200 / no thrown errors
Confidence	No	Absent in scripted scaffold
Raw telemetry	No	No latency/retry spikes
Semantic mismatch	Yes (step 4)	Expected vs observed plan_id_meaning
Recovery (refresh_tool_contract)	Success	Task recovers after remapping

Full specification: docs/roadmap.md
Condensed proposal: docs/research-proposal.md
Taxonomy: docs/failure-taxonomy.md

---

Design principles

1. Benchmark before framework — AgentFailBench stays scaffold-agnostic.
2. Semantics over status codes — expectations and observations are first-class.
3. Label everything — detection lead time and root cause need ground truth.
4. Recovery is a policy — not an infinite retry loop.
5. No false safety claims — empirical reliability evaluation, not formal guarantees.

---

Contributing

Research contributions welcome: new failure cases, detectors, recovery policies, and ablation studies.

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Security reports: SECURITY.md.

---

Citation

@software{parallax2026,
  author  = {Kamineni, Abhinaysai},
  title   = {Parallax: Reliable Agent Systems},
  year    = {2026},
  url     = {https://github.com/askmy-stack/parallax},
  version = {0.1.0}
}

Also see CITATION.cff.

---

License

MIT — see LICENSE.

_{Capable agents must not only know how to act.
They must recognize when their assumptions are failing — and choose when to retry, adapt, ask for help, or stop.}