agentic-sidecar 0.0.1__tar.gz

agentic_sidecar-0.0.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @pramodbn27

agentic_sidecar-0.0.1/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "python"

agentic_sidecar-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      # No [tool.uv.sources] override exists yet (agenticlens integration is
+      # still a placeholder module), so a plain `uv sync` resolves cleanly
+      # without needing --frozen or a sibling checkout.
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff check)
+        run: uv run ruff check src tests
+
+      # Scoped to src/tests, not "." -- ruff >=0.16 formats fenced ```python
+      # blocks inside Markdown by default, and this repo's docs (README.md,
+      # ROADMAP.md, concept.md) intentionally use abbreviated pseudocode
+      # in those fences that isn't meant to be reformatted as real source.
+      - name: Format check (ruff format)
+        run: uv run ruff format --check src tests
+
+      - name: Type check (mypy)
+        run: uv run mypy
+
+      - name: Test (pytest)
+        run: uv run pytest
+
+  package:
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --extra dev --python 3.12
+      - name: Build distributions
+        run: |
+          uv run python -m build
+          uv run python -m twine check dist/*
+
+  # TODO(v0.1+, once agentic_sidecar.integrations.agenticlens has real code):
+  # add a test-agenticlens-integration job that checks out a sibling
+  # `agenticlens` repo and runs `uv sync --extra dev --extra agenticlens`
+  # against it. Not added yet -- there's nothing in that module to exercise.

agentic_sidecar-0.0.1/.github/workflows/release-pypi.yml

@@ -0,0 +1,46 @@
+name: publish-pypi
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC) -- no API token/secret needed
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentic_sidecar-0.0.1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+dist/
+build/
+site/
+.env

agentic_sidecar-0.0.1/AGENTS.md

@@ -0,0 +1,131 @@
+## agentic-sidecar Development Reference
+
+## Status
+
+This repository is a **scaffold** — directory layout, tooling config, and
+CI/release workflows exist; `src/agentic_sidecar/` modules are placeholders
+(docstring only, `NotImplementedError` on any callable if one exists) until
+their version lands. See [ROADMAP.md](ROADMAP.md) for the build order before
+adding real logic to any module.
+
+## Build and Run
+
+- Install: `make install` (runs `uv sync --extra dev`)
+- Test: `make test` or `make check` (lint + format + typecheck + test)
+- Lint: `make lint`
+- Type check: `make typecheck`
+- CLI: not implemented yet — `[project.scripts]` is intentionally absent
+  from `pyproject.toml` until `cli/main.py` has a real Typer `app` (v0.5)
+
+## Code Style
+
+- Strict typing (mypy strict mode, Python 3.10+)
+- Line length: 100
+- Ruff rules: E, F, I, UP, B, SIM, N
+- One purpose per file (separation of concerns)
+- Decision and Intent Envelope artifacts must be exportable as AI Operations
+  Specification objects once implemented (see `ai-operations-spec`)
+
+## Design Constraints
+
+These are load-bearing, not preferences — see
+[ROADMAP.md § Design Constraints](ROADMAP.md#design-constraints-read-before-building-v01)
+for the full rationale on each:
+
+1. **One framework adapter first.** `adapters/langgraph.py` before any of
+   the other four. Do not claim framework independence until a second
+   adapter has been built against real usage.
+2. **Rules before models.** v0.1's `gate/policy.py` and `gate/risk.py` must
+   work with zero LLM calls. Don't reach for `evaluators/judge.py` (v0.3)
+   to solve a v0.1 problem.
+3. **`on_sidecar_failure` has no default.** Every Decision Gate path must
+   handle `fail_open` and `fail_closed` explicitly — this is a governance
+   property, not an implementation detail.
+4. **A risk classifier is not a free lunch.** Keep `gate/risk.py` rule-based
+   until there's measured evidence (see the v0.2.x benchmark in
+   [ROADMAP.md](ROADMAP.md)) that a model-based classifier is actually
+   needed.
+5. **Policy, Risk, and Intent ask different questions.** A change that adds
+   a static allow/deny check to `intent/` belongs in `gate/policy.py`
+   instead. See
+   [README.md](README.md#how-the-decision-gate-evaluates-a-decision).
+
+## Repo Map
+
+| Path | Purpose | Planned version |
+|------|---------|------------------|
+| `src/agentic_sidecar/core/` | `Sidecar` class, `attach()`, decision-boundary interception, `Decision` type | v0.1 |
+| `src/agentic_sidecar/gate/policy.py` | Policy Advisor — deterministic YAML allow/deny rules | v0.1 |
+| `src/agentic_sidecar/gate/risk.py` | Risk Evaluator — rule-based classification | v0.1 |
+| `src/agentic_sidecar/gate/budget.py` | Budget Guardian — cost/token ceilings | v0.4 |
+| `src/agentic_sidecar/adapters/langgraph.py` | LangGraph interception adapter | v0.1 |
+| `src/agentic_sidecar/intent/` | `IntentEnvelope`, alignment scoring, drift detection | v0.2 |
+| `src/agentic_sidecar/evaluators/planner.py` | Planner — evaluates the whole plan against intent | v0.3 |
+| `src/agentic_sidecar/evaluators/critic.py` | Critic mode — pre-decision challenge | v0.3 |
+| `src/agentic_sidecar/evaluators/judge.py` | Model-agnostic LLM Judge interface | v0.3 |
+| `src/agentic_sidecar/gate/` (full outcome set) | `WARN` / `CHALLENGE` / `REPLAN` / `PAUSE` / `ESCALATE`, human-in-the-loop escalation | v0.4 |
+| `src/agentic_sidecar/status/narrate.py` | Human-readable status narration | v0.5 |
+| `src/agentic_sidecar/cli/` | CLI entry point (`agentic-sidecar status --follow`) | v0.5 |
+| `src/agentic_sidecar/adapters/{crewai,autogen,openai_agents,google_adk}.py` | Additional framework adapters | v0.6 |
+| `src/agentic_sidecar/integrations/agenticlens.py` | Optional AgenticLens adapter (surfaces Sidecar decisions in `agenticlens analyze`) | optional, coordinate with `agenticlens` |
+| `src/agentic_sidecar/integrations/agentic_chaos.py` | Optional Agentic Chaos coordination (recovery-decision evaluation, chaos-testing the Sidecar's own gate) | optional, coordinate with `agentic-chaos` |
+| `tests/` | Pytest test suite | ongoing |
+| `Makefile` | Local dev automation | — |
+
+Full architecture and build order: [ROADMAP.md](ROADMAP.md).
+
+## Entry Points (planned)
+
+- Injection API: `from agentic_sidecar import Sidecar`
+- CLI: `agentic-sidecar status --follow` (v0.5)
+
+## Package Boundaries
+
+- This package is **standalone** — `pip install agentic-sidecar` must work
+  with zero other DeepAgentLabs dependencies.
+- AgenticLens integration is optional (`agentic_sidecar.integrations.agenticlens`)
+  and must auto-skip in tests if `agenticlens` is not installed.
+- `core/` must not import from `adapters/` (adapters depend on core, not the
+  reverse).
+- `gate/` (Policy, Risk) must work with zero dependency on `evaluators/`
+  (Planner, Critic, Judge) — v0.1's Decision Gate has to function before
+  Judge exists at all.
+- `evaluators/judge.py` must stay model-agnostic — no hardcoded provider SDK
+  imports at module scope.
+
+## Adding a New Framework Adapter
+
+1. Confirm a first adapter (`adapters/langgraph.py`) is done and stable —
+   don't start a second adapter to "save time" in parallel; the interception
+   abstraction needs to survive one real framework before generalizing.
+2. Add the adapter module under `adapters/`.
+3. Add conformance tests asserting identical `Decision` behavior for an
+   equivalent scenario across all adapters shipped so far.
+4. Update README's `Design Constraints` note if the abstraction had to
+   change to accommodate the new framework.
+
+## Feature Completion Expectations
+
+- Every behavior change must include tests.
+- User-facing features must include or update examples in `README.md` or
+  `examples/`.
+- When a roadmap item or milestone meaningfully changes status, update
+  `README.md` and `ROADMAP.md` in the same change.
+- When work is packaged as a release-ready change, also update
+  `pyproject.toml`, `src/agentic_sidecar/__init__.py`, and `CHANGELOG.md`.
+
+## Pre-push Checklist
+
+Run `make check` before every push. It runs: lint → format-check → typecheck → test.
+
+## Release
+
+1. Bump version in `pyproject.toml`, `src/agentic_sidecar/__init__.py`, and `CHANGELOG.md`
+2. Commit: `git commit -am "release: vX.Y.Z"`
+3. Tag: `git tag vX.Y.Z`
+4. Push: `git push origin main --tags`
+
+The `release-pypi.yml` workflow triggers on the tag push and publishes to
+PyPI via Trusted Publishing (OIDC) — no API token/secret required, but the
+`pypi` GitHub Environment must exist and be configured as a Trusted
+Publisher on PyPI before the first release.

agentic_sidecar-0.0.1/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [Unreleased]
+
+## [0.0.1] - 2026-08-12
+
+### Added
+
+- Initial repository scaffold: proposed package layout under
+  `src/agentic_sidecar/` (placeholder modules only, no logic), `pyproject.toml`,
+  `Makefile`, CI and PyPI-release GitHub Actions workflows, and contributor
+  docs (`AGENTS.md`, `CONTRIBUTING.md`, `CI.md`, `SECURITY.md`).
+- `README.md` and `ROADMAP.md` describing the architecture and v0.1–v1.0
+  build plan.
+- Reserved (not implemented) optional integration seats for both sibling
+  projects: `agenticlens` and `agentic-chaos` extras in `pyproject.toml`,
+  each with a docstring-only placeholder under
+  `src/agentic_sidecar/integrations/`.
+
+### Fixed
+
+- Audited `README.md`/`ROADMAP.md` against the original concept doc and
+  corrected two gaps: the `Planner` module was named throughout the docs
+  but had no package file, version, or repo-map entry (now
+  `evaluators/planner.py`, v0.3); the `CHALLENGE` Decision Gate outcome was
+  dropped from every enumeration while `ROADMAP.md` still claimed "all
+  seven" outcomes (now restored, v0.4). Also documented two previously
+  silent scope cuts (`LangChain` folded into the `LangGraph` adapter;
+  sampling/caching/async-advisory cost-control ideas left unscheduled)
+  instead of leaving them unexplained.
+
+### Changed
+
+- Renamed `future-plans.md` to `concept.md` and updated every reference.
+
+No functional code has shipped yet — see [ROADMAP.md](ROADMAP.md) for the
+v0.1 scope (Sidecar Runtime + Rule-Based Decision Gate).

agentic_sidecar-0.0.1/CI.md

@@ -0,0 +1,70 @@
+# CI Readiness — Pre-push Checklist
+
+Run these checks locally before every push or PR.
+
+## Docs-only shortcut
+
+If your diff only touches `.md` files, skip code checks. Verify with:
+
+```bash
+git status --short
+```
+
+## Required checks (all code changes)
+
+```bash
+make check
+```
+
+This runs lint → format-check → typecheck → test in sequence. If any step
+fails, fix it before pushing.
+
+Or run steps individually:
+
+1. **Clean tree** — no accidental untracked files, no `.env` or secrets
+
+   ```bash
+   git status --short
+   ```
+
+2. **Lint**
+
+   ```bash
+   make lint
+   ```
+
+3. **Format**
+
+   ```bash
+   make format-check
+   ```
+
+   If it fails: `make format && make format-check`
+
+4. **Type check**
+
+   ```bash
+   make typecheck
+   ```
+
+5. **Test**
+
+   ```bash
+   make test
+   ```
+
+## When to run full coverage
+
+Run `make test-cov` instead of `make test` for any change to `core/`,
+`gate/`, or `intent/` — those hold the Decision Gate logic every other
+module depends on.
+
+## CI parity
+
+The GitHub Actions CI workflow runs one job today: lint, format-check,
+type-check, and test across Python 3.10–3.13, then a build/package check.
+If `make check` passes locally, CI should pass too.
+
+A second job testing `agentic_sidecar.integrations.agenticlens` against a
+real `agenticlens` checkout should be added once that module has real code,
+not before.

agentic_sidecar-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+Thanks for helping make `agentic-sidecar` better for everyone building
+governable autonomous AI agents.
+
+`agentic-sidecar` is currently a **scaffold** — see
+[ROADMAP.md](ROADMAP.md) for what's planned and in what order before
+starting on a module.
+
+## Local setup
+
+```bash
+git clone https://github.com/pramodbn27/agentic-sidecar.git
+cd agentic-sidecar
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Or with `uv`:
+
+```bash
+uv sync --extra dev
+```
+
+## Development workflow
+
+1. Check [ROADMAP.md](ROADMAP.md) for the current build order — modules
+   have a stated planned version for a reason (see its Design Constraints
+   section); don't jump ahead (e.g. building Judge before the v0.1
+   rule-based Decision Gate is solid).
+2. Create a focused branch from `main`.
+3. Add or update tests with every behavior change.
+4. Add or update user-facing examples when the feature or expected workflow
+   changes.
+5. If a roadmap item is completed or its status changes, update
+   `README.md` and `ROADMAP.md` in the same pull request.
+6. If the work is release-ready, update `pyproject.toml`,
+   `src/agentic_sidecar/__init__.py`, and `CHANGELOG.md` as part of the
+   release.
+7. Run:
+
+```bash
+ruff check .
+ruff format --check .
+mypy
+pytest
+```
+
+8. Keep PRs focused — one concern per pull request.
+9. Write clear commit messages describing *why*, not just *what*.
+
+## Turning a placeholder module into a real one
+
+1. Read the module's docstring in `src/agentic_sidecar/` — it states what
+   the module is for and which ROADMAP version it belongs to.
+2. Implement against the Python API sketched in `README.md`'s
+   [Planned Python API](README.md#planned-python-api) section, adjusting
+   the README if the real shape needs to differ.
+3. Respect the Package Boundaries in [AGENTS.md](AGENTS.md) (e.g. `gate/`
+   must not depend on `evaluators/`).
+4. Add tests in `tests/`.
+5. Add or update a usage example.
+6. Update README, ROADMAP, and CHANGELOG in the same PR.
+
+## Releases
+
+Releases are automated via GitHub Actions when a version tag is pushed.
+
+### Release checklist
+
+1. Update the version string in all three locations:
+   - `pyproject.toml` → `version = "X.Y.Z"`
+   - `src/agentic_sidecar/__init__.py` → `__version__ = "X.Y.Z"`
+   - `CHANGELOG.md` → add a `## [X.Y.Z] - YYYY-MM-DD` section
+2. Commit: `git commit -am "release: vX.Y.Z"`
+3. Tag: `git tag vX.Y.Z`
+4. Push: `git push origin main --tags`
+
+The `release-pypi.yml` workflow triggers on the tag push and publishes to
+PyPI via Trusted Publishing (OIDC).

agentic_sidecar-0.0.1/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.

agentic_sidecar-0.0.1/Makefile

@@ -0,0 +1,36 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help install lint format format-check typecheck test test-cov clean build
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install dependencies (dev extras)
+	uv sync --extra dev
+
+lint: ## Run ruff linter
+	uv run ruff check src tests
+
+format: ## Auto-format code
+	uv run ruff format src tests
+
+format-check: ## Check formatting without changes
+	uv run ruff format --check src tests
+
+typecheck: ## Run mypy type checking
+	uv run mypy
+
+test: ## Run tests
+	uv run pytest
+
+test-cov: ## Run tests with coverage
+	uv run pytest --cov --cov-report=term-missing
+
+clean: ## Remove build artifacts
+	rm -rf dist/ build/ *.egg-info src/*.egg-info .mypy_cache .pytest_cache .ruff_cache
+
+build: ## Build package distributions
+	uv run python -m build
+
+check: lint format-check typecheck test ## Run all quality gates