agentic-sidecar 0.0.1__py3-none-any.whl

agentic_sidecar/__init__.py

@@ -0,0 +1,15 @@
+"""agentic-sidecar: a companion intelligence and real-time decision
+supervision layer for autonomous AI agents.
+
+    The Main Agent acts. The Sidecar observes, thinks, advises, and governs.
+
+This package is currently a **scaffold** -- directory layout, tooling, and
+CI/release workflows exist, but nothing under `agentic_sidecar` is
+implemented yet. See ROADMAP.md for the build order, starting with a
+rule-based, LLM-free v0.1 Decision Gate, and README.md for the architecture
+and planned Python API.
+"""
+
+__version__ = "0.0.1"
+
+__all__ = ["__version__"]

agentic_sidecar/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""Framework adapters -- the `before_tool_call` / decision-boundary
+interception point for each supported agent framework.
+
+`langgraph.py` is the only adapter planned for v0.1. Do not start a second
+adapter before it is done and stable -- the interception abstraction needs
+to survive contact with one real framework first (ROADMAP.md's Design
+Constraint 1). The other four are placeholders for v0.6.
+"""

agentic_sidecar/adapters/autogen.py

@@ -0,0 +1,7 @@
+"""AutoGen interception adapter.
+
+Not started until `adapters/langgraph.py` (v0.1) is done and stable --
+see ROADMAP.md's Design Constraint 1.
+
+Planned for v0.6 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/adapters/crewai.py

@@ -0,0 +1,7 @@
+"""CrewAI interception adapter.
+
+Not started until `adapters/langgraph.py` (v0.1) is done and stable --
+see ROADMAP.md's Design Constraint 1.
+
+Planned for v0.6 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/adapters/google_adk.py

@@ -0,0 +1,7 @@
+"""Google Agent Development Kit (ADK) interception adapter.
+
+Not started until `adapters/langgraph.py` (v0.1) is done and stable --
+see ROADMAP.md's Design Constraint 1.
+
+Planned for v0.6 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/adapters/langgraph.py

@@ -0,0 +1,7 @@
+"""LangGraph interception adapter -- the first and, until it's proven out,
+only decision-boundary hook. LangGraph was chosen as the starting framework
+because its explicit graph/node structure gives `before_tool_call`-style
+interception the clearest place to attach.
+
+Planned for v0.1 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/adapters/openai_agents.py

@@ -0,0 +1,7 @@
+"""OpenAI Agents SDK interception adapter.
+
+Not started until `adapters/langgraph.py` (v0.1) is done and stable --
+see ROADMAP.md's Design Constraint 1.
+
+Planned for v0.6 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/cli/__init__.py

@@ -0,0 +1,7 @@
+"""CLI entry point.
+
+`[project.scripts]` in pyproject.toml intentionally does not point here yet
+-- add it once `main.py` has a real Typer `app`.
+
+Planned for v0.5 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/cli/main.py

@@ -0,0 +1,5 @@
+"""`agentic-sidecar status --follow` -- live status stream backed by
+`status/narrate.py`.
+
+Planned for v0.5 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/core/__init__.py

@@ -0,0 +1,5 @@
+"""Sidecar runtime: attach() an existing agent, intercept decision
+boundaries, and produce Decision objects.
+
+Planned for v0.1 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/core/context.py

@@ -0,0 +1,6 @@
+"""`DecisionContext` -- what gets passed to every evaluator (Policy, Risk,
+Intent, Critic, Judge) at a decision boundary: the proposed tool call, the
+active IntentEnvelope, accumulated execution history, and risk metadata.
+
+Planned for v0.1 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/core/decision.py

@@ -0,0 +1,9 @@
+"""`Decision(status, risk, reason, ...)` -- the Decision Gate's output type.
+
+v0.1 ships `status in {"ALLOW", "BLOCK"}` only. The full outcome set
+(`ALLOW`, `WARN`, `REPLAN`, `PAUSE`, `BLOCK`, `ESCALATE`) lands in v0.4 --
+see README.md's "How the Decision Gate evaluates a decision" and
+ROADMAP.md's build order.
+
+Planned for v0.1 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/core/sidecar.py

@@ -0,0 +1,9 @@
+"""The `Sidecar` class -- `Sidecar(roles=[...])` and `sidecar.attach(agent)`.
+
+Owns module configuration (which of Policy/Risk/Intent/Critic/Judge/Budget
+are enabled) and the required `on_sidecar_failure` setting (`fail_open` /
+`fail_closed`, no default -- see README.md and ROADMAP.md's Design
+Constraints).
+
+Planned for v0.1 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/evaluators/__init__.py

@@ -0,0 +1,14 @@
+"""Planner, Critic, and Judge -- independent evaluation of a proposed plan
+or decision.
+
+Unlike `gate/` (Policy, Risk), these modules may call an LLM, and it should
+never be the same model/provider as the Main Agent by default (see
+README.md § Sidecar modules -- model independence). All three stay optional
+and off by default (`judge.enabled: false`) given the cost/latency
+tradeoff.
+
+Planner evaluates the whole plan; Critic challenges one decision at a time;
+Judge is the pluggable model-agnostic scoring interface both can call into.
+
+Planned for v0.3 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/evaluators/critic.py

@@ -0,0 +1,6 @@
+"""Critic mode -- challenges a proposed decision before it executes: looks
+for unsupported assumptions, unnecessary actions, contradictions, and
+alternative approaches.
+
+Planned for v0.3 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/evaluators/judge.py

@@ -0,0 +1,9 @@
+"""Model-agnostic LLM Judge interface.
+
+Main Agent model and Sidecar Judge model must be independently swappable --
+at least two provider backends should exist to prove this isn't just a
+wrapper around whichever SDK is imported first (README.md § Sidecar
+modules, "model independence").
+
+Planned for v0.3 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/evaluators/planner.py

@@ -0,0 +1,17 @@
+"""Planner -- independently evaluates the Main Agent's *plan*, before
+individual decisions within it reach the Decision Gate.
+
+Distinct from Critic (critic.py), which challenges a single proposed
+decision right before it executes: Planner looks at the whole multi-step
+plan against the active IntentEnvelope and flags steps that exceed what
+was actually asked for (e.g. the user requested an explanation, the plan
+includes a cancellation and a refund -- see the DEV/production-cleanup and
+"explain my charge" examples this mirrors). Its output feeds the
+`CHALLENGE` / `REPLAN` Decision Gate outcomes the same way Critic's does.
+
+Planned for v0.3, alongside Critic and Judge -- like both, it requires real
+reasoning rather than a deterministic check, so it doesn't ship until v0.1/
+v0.2's LLM-free phase is done (see ROADMAP.md's Design Constraint 2).
+
+Not implemented yet.
+"""

agentic_sidecar/gate/__init__.py

@@ -0,0 +1,12 @@
+"""The Decision Gate: Policy Advisor, Risk Evaluator, and Budget Guardian.
+
+Answers "are you permitted to do this?" (policy.py) and "how dangerous is
+this action?" (risk.py) -- deliberately separate from `intent/`, which
+answers the harder question "is this actually what the human asked you to
+accomplish?" See README.md's "How the Decision Gate evaluates a decision"
+and ROADMAP.md's Design Constraint 5 before adding a check here that's
+really an intent question.
+
+`policy.py` and `risk.py` are planned for v0.1 (rule-based, zero LLM calls).
+`budget.py` is planned for v0.4. Not implemented yet.
+"""

agentic_sidecar/gate/budget.py

@@ -0,0 +1,5 @@
+"""Budget Guardian -- cost/token ceilings enforced per task, through the same
+Decision Gate as Policy and Risk rather than a side channel.
+
+Planned for v0.4 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/gate/policy.py

@@ -0,0 +1,8 @@
+"""Policy Advisor -- deterministic, YAML-driven allow/deny rules.
+
+Answers "are you permitted to do this?" only. No LLM calls, no intent
+awareness -- that's `intent/` and `evaluators/`, deliberately kept separate
+(see ROADMAP.md's Design Constraint 5).
+
+Planned for v0.1 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/gate/risk.py

@@ -0,0 +1,9 @@
+"""Risk Evaluator -- classifies a proposed action's risk level.
+
+v0.1-v0.2: static rules only (tool name, argument pattern, destination).
+Promote to an optional small local model only once there's measured
+evidence the rule-based version is the bottleneck (ROADMAP.md's Design
+Constraint 4 -- a risk classifier is not a free lunch).
+
+Planned for v0.1 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/integrations/__init__.py

@@ -0,0 +1,13 @@
+"""Optional adapters to sibling DeepAgentLabs projects.
+
+Nothing in `agentic_sidecar`'s core ever imports this package -- each module
+here is its own opt-in extra (`pip install agentic-sidecar[agenticlens]` /
+`[agentic-chaos]`) and must degrade gracefully (auto-skip in tests) when the
+target package isn't installed.
+
+- `agenticlens.py` -- one-way export: Sidecar decisions -> AgenticLens Workflow.
+- `agentic_chaos.py` -- two-way, same-run coordination for recovery-decision
+  evaluation and chaos-testing the Sidecar's own gate.
+
+Both are placeholders; neither has real code yet.
+"""

agentic_sidecar/integrations/agentic_chaos.py

@@ -0,0 +1,26 @@
+"""Optional Agentic Chaos coordination.
+
+Unlike the AgenticLens adapter (a one-way export after the fact, merging a
+completed Sidecar session onto a `Workflow`), this is a two-way, same-run
+relationship: Agentic Chaos and the Sidecar both attach to the *same* agent
+invocation. Agentic Chaos injects a fault; the Sidecar's Decision Gate
+evaluates the agent's recovery attempt through its normal Policy/Risk/Intent
+checks, answering not just "did it recover?" but "was the recovery decision
+itself appropriate?".
+
+Also relevant in the other direction: chaos-testing the Sidecar's own gate
+by injecting a fault into the Sidecar's evaluation path itself, to verify
+`on_sidecar_failure` (`fail_open` / `fail_closed`) behaves as configured
+when the Sidecar times out or errors.
+
+The concrete integration surface -- what this module reads from an active
+chaos session, what it reports back, and whether that needs a shared schema
+the way the AgenticLens adapter does -- isn't designed yet. See
+ROADMAP.md's Cross-Project Dependencies (`agentic-chaos`: "Coordinate
+with").
+
+Not core-dependency: `agentic_sidecar`'s runtime never imports this module
+on its own. Requires `pip install agentic-sidecar[agentic-chaos]`.
+
+Not yet scheduled to a specific ROADMAP version. Not implemented yet.
+"""

agentic_sidecar/integrations/agenticlens.py

@@ -0,0 +1,14 @@
+"""Optional AgenticLens adapter -- surfaces Sidecar Decision events
+(allow/warn/replan/block, intent-alignment score) as AgenticLens `Workflow`
+step data, so `agenticlens analyze` can report on them alongside cost and
+latency. Expected shape: an `attach_events()` / `step_kwargs()`-style pair --
+one call to merge a completed Sidecar session onto a `Workflow`, one helper
+to pass Sidecar's own step correlation IDs through cleanly.
+
+Not core-dependency: `agentic_sidecar`'s runtime never imports this module
+on its own. Requires `pip install agentic-sidecar[agenticlens]`.
+
+Not yet scheduled to a specific ROADMAP version -- see ROADMAP.md's
+Cross-Project Dependencies (`agenticlens`: "Validate in"). Not implemented
+yet.
+"""

agentic_sidecar/intent/__init__.py

@@ -0,0 +1,11 @@
+"""Intent Guardian -- structured IntentEnvelope, intent injection at decision
+boundaries, drift detection, and constraint validation.
+
+Answers "is this actually what the human asked you to accomplish?" -- the
+project's actual differentiator (see README.md's "How the Decision Gate
+evaluates a decision"). Keep this module's checks semantic, not a
+permission list in disguise; static allow/deny checks belong in
+`gate/policy.py` instead (ROADMAP.md's Design Constraint 5).
+
+Planned for v0.2 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/intent/alignment.py

@@ -0,0 +1,10 @@
+"""Intent-drift detection and constraint validation -- is the current
+proposed action still consistent with the active IntentEnvelope's goal,
+constraints, and granted authority?
+
+Deterministic where possible (e.g. `proposed_refund > envelope.constraints.maximum_refund`)
+so this stays checkable without an LLM -- see the v0.2.x Early Validation
+Benchmark in ROADMAP.md, which measures exactly this module's catch rate.
+
+Planned for v0.2 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/intent/envelope.py

@@ -0,0 +1,10 @@
+"""`IntentEnvelope` -- goal, requester, constraints, granted/denied
+authority, and expiry (see README.md § Sidecar modules for the YAML shape).
+
+When this is actually designed, account for the v1.0 target of publishing
+it as a cross-project interoperability schema (README.md's "Long-term: an
+intent propagation layer") -- e.g. a `parent_intent_id` for delegation
+chains -- even though nothing consumes that field until v1.0.
+
+Planned for v0.2 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/status/__init__.py

@@ -0,0 +1,5 @@
+"""Status Interpreter -- translates raw tool/MCP traces into human-readable
+live narration (e.g. "Looking up your order" instead of `GET /orders/182`).
+
+Planned for v0.5 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar/status/narrate.py

@@ -0,0 +1,6 @@
+"""Narration rendering -- raw execution event in, human-readable status line
+out. Backs the `agentic-sidecar status --follow` CLI (cli/main.py, also
+v0.5).
+
+Planned for v0.5 -- see ROADMAP.md. Not implemented yet.
+"""

agentic_sidecar-0.0.1.dist-info/METADATA

@@ -0,0 +1,466 @@
+Metadata-Version: 2.5
+Name: agentic-sidecar
+Version: 0.0.1
+Summary: Companion intelligence and real-time decision supervision for autonomous AI agents.
+Project-URL: Homepage, https://github.com/DeepAgentLabs/agentic-sidecar
+Project-URL: Repository, https://github.com/DeepAgentLabs/agentic-sidecar
+Project-URL: Issues, https://github.com/DeepAgentLabs/agentic-sidecar/issues
+Project-URL: Changelog, https://github.com/DeepAgentLabs/agentic-sidecar/blob/main/CHANGELOG.md
+Author: agentic-sidecar Contributors
+License: MIT License
+        
+        Copyright (c) 2026 pramodbn27
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,decision-supervision,governance,intent,llm,safety
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: agentic-chaos
+Requires-Dist: agentic-chaos>=0.1; extra == 'agentic-chaos'
+Provides-Extra: agenticlens
+Requires-Dist: agenticlens>=0.1.3; extra == 'agenticlens'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentic-sidecar
+
+**A companion intelligence and real-time supervision layer for autonomous AI agents.**
+
+> The Main Agent acts. The Sidecar observes, thinks, advises, and governs.
+
+## Status
+
+**Concept / pre-implementation.** This repository currently contains the
+architecture proposal ([`concept.md`](concept.md)) and this README
+— no package code, no PyPI release, no CI yet. See
+[ROADMAP.md](ROADMAP.md) for the build plan, starting with a narrow,
+LLM-free v0.1.
+
+## Contents
+
+- [Why](#why)
+- [What it is not](#what-it-is-not)
+- [Architecture](#architecture)
+- [Sidecar vs. Agent Harness](#sidecar-vs-agent-harness)
+- [Main Agent vs. Sidecar](#main-agent-vs-sidecar)
+- [How the Decision Gate evaluates a decision](#how-the-decision-gate-evaluates-a-decision)
+- [Sidecar modules](#sidecar-modules)
+- [Planned Python API](#planned-python-api)
+- [Operating modes](#operating-modes)
+- [Long-term: an intent propagation layer](#long-term-an-intent-propagation-layer)
+- [The DeepAgentLabs ecosystem](#the-deepagentlabs-ecosystem)
+- [Roadmap](#roadmap)
+- [License](#license)
+
+## Why
+
+Autonomous agents chain a lot of reasoning and tool calls between a user's
+request and a real-world effect:
+
+```text
+User → Agent → Planning → Sub-Agent → MCP → Tool → API → External System
+```
+
+Three things go wrong in that chain that permission checks alone don't catch:
+
+- **Intent drift** — "investigate why production is slow" quietly becomes
+  "restart the production database." Nobody revoked authority; the agent's
+  plan just wandered.
+- **Technically-allowed, contextually-wrong actions** — `refund_customer()`
+  is a permitted tool call. Refunding $850 against a $500 authorization is
+  not a permitted *decision*, even though the tool call succeeds.
+- **No live visibility** — long-running agents act for minutes at a time
+  with no answer to "what is it doing right now, and can I stop it?"
+
+`agentic-sidecar` is designed to attach to any agent framework, but the first
+release proves that against one framework only — LangGraph — before claiming
+the rest (see [Design Constraints](ROADMAP.md#design-constraints-read-before-building-v01)
+in ROADMAP.md). Either way, it answers a different question than permission
+checks or observability tools do:
+
+> **Not** "can this agent call this tool?" — **"should it, right now, given
+> what the user actually asked for?"**
+
+## What it is not
+
+- **Not a multi-agent framework.** The Sidecar never owns or executes the
+  task plan, and it never replaces a worker agent. It may independently
+  critique the Main Agent's plan or propose alternatives (the Planner
+  module) — but the Main Agent decides whether to act on that critique, and
+  remains the one that executes.
+- **Not a content-safety guardrail.** Libraries like NeMo Guardrails or
+  Guardrails AI validate a single prompt/response turn against rules. The
+  Sidecar evaluates a *decision* — a tool call or plan step — against intent
+  and context accumulated across an entire task.
+- **Not a tracing/observability tool.** That's
+  [AgenticLens](https://github.com/DeepAgentLabs/agenticlens)'s job:
+  "what did the agent do, and why did it fail?" — after the fact. The
+  Sidecar's job is "should it continue?" — while it's still running.
+- **Not just LLM-as-a-Judge.** A judge model is one possible evaluator inside
+  one Sidecar module (§ [Sidecar modules](#sidecar-modules)). Most decisions
+  should never reach an LLM at all — see [Operating
+  modes](#operating-modes) and the cost-control design in
+  [ROADMAP.md](ROADMAP.md).
+- **Not an agent harness.** It doesn't run the agent loop, manage tools, or
+  handle retries — that's LangGraph's, CrewAI's, or your custom loop's job.
+  The Sidecar attaches to whatever harness is already running the agent; see
+  [Sidecar vs. Agent Harness](#sidecar-vs-agent-harness).
+
+## Architecture
+
+```text
+                    USER
+                      │
+                 User Intent
+                      │
+                      ▼
+              ┌───────────────┐
+              │  MAIN AGENT   │
+              │   EXECUTOR    │
+              └───────┬───────┘
+                      │
+              Plans / Decisions
+                      │
+                      ▼
+            ┌─────────────────────┐
+            │   AGENTIC SIDECAR   │
+            │                     │
+            │ Intent Guardian     │
+            │ Planner             │
+            │ Critic              │
+            │ Judge               │
+            │ Risk Evaluator      │
+            │ Policy Advisor      │
+            │ Decision Gate       │
+            │ Status Interpreter  │
+            └──────────┬──────────┘
+                       │
+          Advice / Approval / Challenge
+                       │
+                       ▼
+                 MAIN AGENT
+                       │
+                       ▼
+                  MCP / Tools
+                       │
+                       ▼
+                External Systems
+```
+
+The Sidecar is attached to the execution lifecycle. It does not own the
+user's task and is never a second worker in the plan.
+
+## Sidecar vs. Agent Harness
+
+An **agent harness** (LangGraph, a custom loop, OpenAI Agents SDK, Microsoft
+Agent Framework, ...) is the control and execution environment: it runs the
+agent loop and manages tools, state, context, retries, and lifecycle.
+`agentic-sidecar` doesn't replace that — it attaches to it as a decision-time
+supervision layer:
+
+```text
+Agent Harness   = control and execution loop.
+Agentic Sidecar = decision-time supervision layer for that loop.
+```
+
+The harness answers *"how do I execute this workflow?"* The Sidecar answers
+*"should this decision happen, given what the human originally asked for?"*
+
+This distinction matters most once a task fans out across a delegation
+chain — Agent A → Agent B → Agent C → MCP/Tool — where each hop tends to
+receive only the sub-task it needs to perform, not the original constraints
+and authority behind it:
+
+```text
+Human Intent → Agent A → delegates → Agent B → delegates → Agent C → MCP/Tool
+```
+
+The Sidecar's Intent Envelope (§ [Sidecar modules](#sidecar-modules)) is
+designed to travel with the task through that chain instead of being
+reconstructed from conversation history at every hop — see [Long-term: an
+intent propagation layer](#long-term-an-intent-propagation-layer).
+
+Where it pays for itself: without a supervision layer, a harness typically
+discovers a bad decision only after acting on it —
+
+```text
+Plan → Act → Fail → Recover → Replan
+```
+
+— versus catching it before execution:
+
+```text
+Plan → Sidecar Check → Act
+          ├── ALLOW
+          ├── CHALLENGE
+          ├── REPLAN
+          ├── BLOCK
+          └── ESCALATE
+```
+
+That's primarily a reliability and control win, not a speed win — the
+Sidecar doesn't make the underlying model faster, it reduces unnecessary
+actions, unsafe retries, and repeated context reconstruction. Full treatment:
+[concept.md § 23](concept.md#23-sidecar-vs-agent-harness).
+
+## Main Agent vs. Sidecar
+
+| Main Agent | Agentic Sidecar |
+| --- | --- |
+| Accomplishes the task | Maintains original intent |
+| Reasons about the domain problem | Independently evaluates plans and decisions |
+| Selects and calls tools | Challenges questionable decisions |
+| Interacts with MCP servers / APIs | Evaluates risk and checks policy |
+| Executes actions | Decides when human approval is required |
+| Produces the final result | Explains live execution; recommends replanning; pauses or blocks when configured |
+
+## How the Decision Gate evaluates a decision
+
+Three modules ask three genuinely different questions about the same
+proposed action, and the roadmap's job is to keep them from collapsing into
+one generic "policy engine":
+
+```text
+             USER INTENT
+                  │
+          Intent Envelope
+                  │
+                  ▼
+             MAIN AGENT
+                  │
+           proposed action
+                  │
+                  ▼
+              SIDECAR
+          ┌───────┼────────┐
+          │       │        │
+       Policy    Risk    Intent
+          │       │        │
+   "Are you    "How      "Is this
+   permitted   dangerous  actually what
+   to do       is this    the human
+   this?"      action?"   asked you to
+                          accomplish?"
+          │       │        │
+          └───────┼────────┘
+                  │
+             DECISION GATE
+                  │
+       ┌──────────┼──────────┐
+       ▼          ▼          ▼
+     ALLOW      REPLAN     ESCALATE
+                              │
+                            HUMAN
+```
+
+Policy and Risk are largely mechanical — permission lists, thresholds,
+tool-argument patterns — and v0.1 ships them with zero LLM calls (see
+[ROADMAP.md](ROADMAP.md)). Intent is the one that requires understanding
+what the user actually meant, and it's where the project's distinctive
+value lives.
+
+The diagram above shows the target outcome set. **v0.1 ships a narrower
+slice**: only `ALLOW`/`BLOCK`, in Observe mode — the Sidecar logs what it
+*would* have decided but cannot yet stop an action in practice. `WARN`,
+`CHALLENGE`, `REPLAN`, `PAUSE`, and `ESCALATE` arrive across v0.2–v0.4 as
+Intent Guardian and the full Decision Gate ship. Version-by-version build
+order is in [ROADMAP.md](ROADMAP.md#build-order).
+
+## Sidecar modules
+
+Users enable only what they need:
+
+```text
+Agentic Sidecar
+│
+├── Intent Guardian     — Intent Envelope, alignment checks, drift detection
+├── Planner              — independently evaluates the agent's plan
+├── Critic                — challenges a proposed decision before it executes
+├── Judge                 — optional independent (and independent-model) evaluation
+├── Risk Evaluator        — classifies an action's risk before deciding whether to escalate
+├── Policy Advisor        — deterministic policy rules (cheapest check, runs first)
+├── Decision Gate         — turns evaluations into ALLOW / WARN / CHALLENGE / REPLAN / PAUSE / BLOCK / ESCALATE
+├── Budget Guardian       — cost/token ceilings per task
+├── Status Interpreter    — translates raw tool/MCP traces into human-readable narration
+└── Human Escalation      — pauses execution and requests approval
+```
+
+```yaml
+sidecar:
+  intent:
+    enabled: true
+    preserve_original_intent: true
+  planner:
+    enabled: false        # off by default — see cost design in ROADMAP.md
+  critic:
+    enabled: false        # off by default — see cost design in ROADMAP.md
+  policy:
+    enabled: true
+    source: policies.yaml
+  risk:
+    enabled: true
+    intervention_threshold: 0.80
+  judge:
+    enabled: false        # off by default — see cost design in ROADMAP.md
+    model: independent-model
+  budget:
+    enabled: true
+    max_cost: 2.00
+  human_approval:
+    enabled: true
+  on_sidecar_failure: fail_closed   # or fail_open — see ROADMAP.md
+```
+
+## Planned Python API
+
+This is the target developer experience — **not yet implemented** (tracked
+as v0.1 in [ROADMAP.md](ROADMAP.md)):
+
+```python
+from agentic_sidecar import Sidecar
+
+sidecar = Sidecar(roles=["intent_guardian", "policy", "risk", "planner", "critic"])
+agent = sidecar.attach(my_agent)
+
+agent.run("Investigate the production issue but do not modify production.")
+```
+
+```python
+@sidecar.before_tool_call
+def evaluate_action(context):
+    return sidecar.evaluate(
+        intent=context.intent,
+        action=context.tool_call,
+        risk=context.risk,
+    )
+```
+
+```python
+Decision(
+    status="REPLAN",
+    risk="HIGH",
+    reason="Action exceeds original user intent",
+)
+```
+
+## Operating modes
+
+| Mode | Behavior |
+| --- | --- |
+| **Observe** | Sidecar monitors and logs; cannot affect execution. |
+| **Advise** | Sidecar returns a recommendation; the agent decides whether to follow it. |
+| **Govern** | Sidecar's Decision Gate can allow, warn, replan, pause, or block. |
+| **Human-supervised** | High-risk decisions route to a human for approve/reject. |
+
+Modes are meant to be adopted in that order — organizations start in Observe
+and move to Govern once they trust the signal.
+
+## Long-term: an intent propagation layer
+
+The nearer-term modules above are the whole of what v0.1–v0.8 ship. But the
+`IntentEnvelope` (§ [Sidecar modules](#sidecar-modules)) is designed to
+survive being handed off — not just checked once and discarded:
+
+```text
+Human
+  │
+  └── Intent Envelope #182
+            │
+            ▼
+         Agent A
+            │
+        delegates
+            ▼
+         Agent B
+            │
+           MCP
+            ▼
+         Agent C
+            │
+           Tool
+```
+
+If every hop in a delegation chain can answer *what was originally
+requested, who authorized it, what constraints apply, what authority was
+actually delegated, and whether intent has since changed* — that's no
+longer just a feature of one package. It's closer to an interoperability
+concern for autonomous systems generally, which is why v1.0 targets
+publishing the envelope as a versioned schema in `ai-operations-spec`
+rather than keeping it as an internal Sidecar structure (see the v1.0 entry
+in [ROADMAP.md](ROADMAP.md#build-order)).
+This is explicitly a v1.0 target, not something v0.1 needs to anticipate —
+noted here because it's the reason the envelope's shape deserves care early,
+even though nothing consumes it across process boundaries yet.
+
+## The DeepAgentLabs ecosystem
+
+```text
+                 DeepAgentLabs
+              Autonomous AI Systems
+                      │
+        ┌─────────────┼─────────────┐
+        │             │             │
+     OBSERVE         GUIDE        CONNECT
+        │             │             │
+ AgenticLens    Agentic Sidecar  Agentic MCP
+        │             │             │
+        └─────────────┼─────────────┘
+                      │
+                     TEST
+                      │
+                Agentic Chaos
+```
+
+| Project | Question it answers |
+| --- | --- |
+| [AgenticLens](https://github.com/DeepAgentLabs/agenticlens) | What did the agent do, and what happened? |
+| [Agentic Chaos](https://github.com/DeepAgentLabs/agentic-chaos) | How does the agent behave when things go wrong? |
+| [Agentic MCP](https://github.com/DeepAgentLabs/mcp-server) | How does the agent interact with tools and external capabilities? |
+| **Agentic Sidecar** | Should the agent continue with this decision, and is it still acting according to intent? |
+
+Each project is independently installable; none requires another as a hard
+dependency (see [Cross-Project Dependencies](ROADMAP.md#cross-project-dependencies)
+in the roadmap).
+
+## Roadmap
+
+Full build plan, version sequencing, and design constraints:
+[ROADMAP.md](ROADMAP.md).
+
+Original architecture proposal: [concept.md](concept.md).
+
+## License
+
+MIT (planned — `LICENSE` file to be added alongside the first code commit,
+matching sibling DeepAgentLabs projects).

agentic_sidecar-0.0.1.dist-info/RECORD

@@ -0,0 +1,33 @@
+agentic_sidecar/__init__.py,sha256=E4IIBe-c1WFUuHRtcUF5sg3Co-7hu18mkDAb_6tYiWI,556
+agentic_sidecar/adapters/__init__.py,sha256=K64pZP-ax-mRit0h9YTer1sql2DNVUBAg7Os6d70-kM,405
+agentic_sidecar/adapters/autogen.py,sha256=8zRlcGEfT2QcifObvrljRbmIac5hK2Pgkw6NWz1DciY,205
+agentic_sidecar/adapters/crewai.py,sha256=rARZMyq-owXF3i6-Dg_DVxgh-H4a5lEjialDtErBrx8,204
+agentic_sidecar/adapters/google_adk.py,sha256=bnJL2fcYXEFlvhybpaZ5GUAU06Yj8Q8uO5jwTIfeL2Y,232
+agentic_sidecar/adapters/langgraph.py,sha256=KQo0S2IaVlaVa2ZpN5fEQrnZD6OlYMObX_ljT3jOkY8,329
+agentic_sidecar/adapters/openai_agents.py,sha256=dt7cT8nUMkY8FgBQjYNXxIJIENEMX0hkLizLe-lgxfc,215
+agentic_sidecar/cli/__init__.py,sha256=izIdMCzY2UDWkCdysIIR9-ViL2e469v-t1kPU6neqFY,208
+agentic_sidecar/cli/main.py,sha256=d0Ax1qxrYWzHV3mMJ90dIuOeNkBXQn68ybLK-pab5kw,152
+agentic_sidecar/core/__init__.py,sha256=DiNE6u0dqGp0dxD00PNlxee64NLQqOt2eTLIckerSU4,171
+agentic_sidecar/core/context.py,sha256=QoqLPvRrR4dWWku7M16rrpDhtBsIWCSe8_MF1u8gZzA,285
+agentic_sidecar/core/decision.py,sha256=aziHx_wCAmNb8nd1Mhd2CeQrdUEMHni_pms04gzm4R0,375
+agentic_sidecar/core/sidecar.py,sha256=Gsj5y12fYUIndElQ6VZvyJJCicZjGcfXGg21hnjuiXs,371
+agentic_sidecar/evaluators/__init__.py,sha256=m51PuQN44CXEpEipvOSIov_u06nFs919GZT2sFhp2Bo,601
+agentic_sidecar/evaluators/critic.py,sha256=-6yd51ivTk4IqS4pdUhQmYFk8AfY21wh7_AbDLLUDvo,231
+agentic_sidecar/evaluators/judge.py,sha256=rlQEKQLy2cMEhSweoPbAZ-7DY4o4ceavYFS1EGzfT1o,350
+agentic_sidecar/evaluators/planner.py,sha256=mE814lo0yP6a3i2vzO0aHNf-ssrVxnPOPQhbfUEOwao,877
+agentic_sidecar/gate/__init__.py,sha256=uz28Bw5LcROPkGFVmq_Khc8uRK3LLg5eiH_hATzO0CY,603
+agentic_sidecar/gate/budget.py,sha256=qwz6MMp2CMrQQfseztATau2fEageZJ3EUKrmcscJebc,201
+agentic_sidecar/gate/policy.py,sha256=xeWzbEtltca6xtoYDXO0_5Qbx9-QU9w85weWs8pgrqE,315
+agentic_sidecar/gate/risk.py,sha256=SVIejZuPUOZYs5ooisj1YHVFGXJuA7tRriHroWPcAQo,395
+agentic_sidecar/integrations/__init__.py,sha256=dCpTYF4TWzM44xAyabQPA33Ae9ZghbowiggqQOvuWPg,587
+agentic_sidecar/integrations/agentic_chaos.py,sha256=XZUjfrqDc0L04M5l56SxXnf1LopvGi3LUUahOEBHQy4,1284
+agentic_sidecar/integrations/agenticlens.py,sha256=J4kXFdzbPZNyzUtEmHY1iQYq06YtiSY5cjvz4GApf-s,726
+agentic_sidecar/intent/__init__.py,sha256=DiVa-1S2ifNvhdnkCYhEeQWr6vQvMPPqQ-IaoP1Ddr4,534
+agentic_sidecar/intent/alignment.py,sha256=48omdh6x2X-s3fMbkzpiCzgUzccm7wwoQqkK03NPa9Q,481
+agentic_sidecar/intent/envelope.py,sha256=FD5DZk2VLrXchUbEywREq8fBJV32u_opFs2tAtCobwc,489
+agentic_sidecar/status/__init__.py,sha256=gLhplCh9koEpD-Jk1kpMYp1mdiXnAiXp5On0cstWcko,214
+agentic_sidecar/status/narrate.py,sha256=N5j8PLeCHoqre_Uf4_SDCeRmNglb7WyDKn5sFwHLdbk,218
+agentic_sidecar-0.0.1.dist-info/METADATA,sha256=MH6-lWn9SJw9VD9x77wkAGzf0j-kPtrJSXohPfEhpZo,18362
+agentic_sidecar-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agentic_sidecar-0.0.1.dist-info/licenses/LICENSE,sha256=asfUZpnkKQnsP0OQ9BE8_TAUEYZz4qUBkwgHPLvSWko,1067
+agentic_sidecar-0.0.1.dist-info/RECORD,,

agentic_sidecar-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentic_sidecar-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pramodbn27
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.