🧠 AAROP — Autonomous Agentic Reasoning & Orchestration Platform

A reference implementation of a multi-agent AI system built on agentic-loop engineering principles: Perceive → Plan → Act → Observe → Reflect → Adapt. The loop is an explicit, inspectable state machine — not a hidden prompt chain — with bounded autonomy, self-verification, durable checkpointing, and full trace replay.

🌐 ▶ Try the Live Demo →

Watch an objective flow through the full agentic loop in real time — no install, no API keys, no sign-up.

Built by Devayan Mandal — AI / ML Engineer.

---

🎯 What's in this repository

Path	What it is
core/	The Python reference engine — the agentic loop, agents, tool registry, memory, model router, observability. 9 tests, 92% coverage. Runs offline, no API keys.
web-demo/	A Next.js live demo (aarop.vercel.app) that animates the full agentic loop in the browser.
docs/AAROP_Case_Study.pdf	A polished 4-page case study (problem → architecture → results → ADRs).
core/docs/ARCHITECTURE.md	C4 diagrams, production reference stack, and 5 ADRs.
core/docs/PROJECT_SPEC.md	The full chief-architect-level system specification.

🔁 The Agentic Loop

PERCEIVE → PLAN → ACT → OBSERVE → REFLECT ──accept──► DONE ✅
   ▲                                  │
   └──────────── ADAPT ◄──────reject──┘   (budget exhausted → ESCALATE 🚨)

Phase	Responsibility
Perceive	Normalize input + retrieve relevant context / memory (RAG)
Plan	Build a cost-aware hierarchical task graph
Act	Invoke schema-validated, sandboxed tools / sub-agents
Observe	Capture structured results + detect anomalies
Reflect	Critic verifies output against acceptance criteria
Adapt	Replan / retry with backoff / escalate to a human

Every phase transition emits a structured trace event, so any run is fully reconstructable and replayable. Every run respects step / cost / time budgets and escalates instead of looping forever.

🗂️ Repository layout

aarop/
├── core/                       # Python reference engine (runs offline, 92% tested)
│   ├── src/aarop/
│   │   ├── core/loop.py        # the agentic loop state machine + Budget guardrails
│   │   ├── agents/agents.py    # Planner · Actor · Verifier (critic)
│   │   ├── tools/registry.py   # schema-validated tools, scopes, circuit breaker, audit log
│   │   ├── memory/store.py     # working / episodic / semantic memory + RAG recall
│   │   ├── routing/            # cost-aware model router (cloud + self-hosted)
│   │   └── observability/      # structured tracing + replay
│   ├── examples/run_demo.py    # end-to-end runnable demo
│   ├── tests/test_loop.py      # 9 unit tests
│   ├── docs/                   # ARCHITECTURE.md, PROJECT_SPEC.md, case study
│   └── .github/workflows/ci.yml
├── web-demo/                   # Next.js 14 live demo (Vercel)
│   ├── app/                    # page.tsx, layout.tsx, globals.css
│   └── lib/aarop.ts            # faithful TypeScript port of the loop
├── docs/AAROP_Case_Study.pdf
└── README.md

⚡ Quickstart

Core engine (Python):

cd core
pip install -e ".[dev]"
python examples/run_demo.py --objective "calculate 21*2 + 8" --verbose
pytest --cov=aarop          # 9 passed · 92% coverage

Live demo (Next.js):

cd web-demo
npm install
npm run dev                 # http://localhost:3000

🏗️ Architecture & engineering rigor

• Explicit loop state machine — observable, replayable, crash-recoverable
• Bounded autonomy — step / cost / time budgets with human escalation
• Self-verification — a critic agent gates every result before commit
• Resilient tooling — schema-validated, permission-scoped, retries + circuit breaker + audit log
• Cost-aware model routing — cloud + self-hosted, pluggable
• Observability — structured trace per run (OpenTelemetry-shaped)
• 92% test coverage on core orchestration; CI across Python 3.10–3.12

See core/docs/ARCHITECTURE.md for C4 diagrams, the production reference stack (Temporal, FastAPI, pgvector, vLLM, Kubernetes, OpenTelemetry), and 5 Architecture Decision Records.

🌐 Live demo

The web-demo/ ports the exact loop logic to TypeScript and runs 100% client-side with a deterministic mock provider — instant, free, and always online. Deployed on Vercel: aarop.vercel.app. See web-demo/README.md for deploy steps.

🗺️ Roadmap

• Pluggable real LLM provider (OpenAI / Anthropic / self-hosted vLLM)
• Persistent memory backend (pgvector / Qdrant) + cross-encoder reranker
• Durable workflow execution via Temporal
• OpenTelemetry exporter + Grafana dashboards
• "Bring your own API key" toggle in the live demo

🤝 Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

📜 License

MIT © 2026 Devayan Mandal — see core/LICENSE.