veille-supervisor 0.3.0__tar.gz

veille_supervisor-0.3.0/.env.example

@@ -0,0 +1,49 @@
+# AI Runtime Supervisor / Veille Console — local development configuration
+# Copy to .env and fill in only if you opt in to real providers.
+
+# --- Infrastructure (Docker Compose environment) ---
+# DATABASE_URL=postgresql://supervisor:supervisor_dev@localhost:5432/supervisor
+# REDIS_URL=redis://localhost:6379/0
+# S3_ENDPOINT=http://localhost:9000
+# S3_ACCESS_KEY=minioadmin
+# S3_SECRET_KEY=minioadmin
+# S3_BUCKET=supervisor-artifacts
+
+# --- Runtime opt-in flags (SUPERVISOR_* namespace, read by the SDK) ---
+# SUPERVISOR_ENFORCE=true
+# SUPERVISOR_PLAN=1
+# SUPERVISOR_OPTIMIZE=1
+# SUPERVISOR_OPTIMIZE_MODE=active
+# SUPERVISOR_CACHE_APPROVED=1
+# SUPERVISOR_MEMORY=1
+
+# --- Console mode (VEILLE_* namespace, read by the ``veille`` CLI) ---
+# Default (off) runs everything in mock mode — no API keys, no external calls.
+VEILLE_REAL_MODE=false
+# VEILLE_PROVIDER=openai
+# VEILLE_MODEL=gpt-4o
+# VEILLE_TOOL_API_BASE_URL=http://localhost:8001
+
+# --- Model provider keys (opt-in; mock is default) ---
+# OPENAI_API_KEY=
+# OPENROUTER_API_KEY=
+# ANTHROPIC_API_KEY=
+# GEMINI_API_KEY=
+# LITELLM_MODEL=gpt-4o-mini
+
+# --- Cache ---
+VEILLE_CACHE_BACKEND=memory
+# VEILLE_CACHE_APPROVED=true
+
+# --- Policy overrides ---
+# VEILLE_OPTIMIZE=true
+# VEILLE_ENFORCE=true
+
+# --- Context optimization ---
+# VEILLE_CONTEXT_COMPRESSION=true
+# VEILLE_CONTEXT_DIVERSIFICATION=true
+
+# --- Observability ---
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# OTEL_SERVICE_NAME=veille-dev
+LOG_LEVEL=INFO

veille_supervisor-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src tests examples
+
+      - name: Ruff format check
+        run: ruff format --check src tests examples
+
+      - name: Mypy
+        run: mypy src/supervisor
+
+      - name: Pytest
+        run: pytest -v

veille_supervisor-0.3.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Environment
+.env
+.env.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project artifacts
+*.log
+.mypy_cache/
+
+# Local databases
+*.db
+*.sqlite
+*.sqlite3
+*.duckdb
+
+# Coverage outputs
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Node / UI
+node_modules/
+ui/dist/
+ui/node_modules/
+*.tsbuildinfo

veille_supervisor-0.3.0/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+All notable changes are documented here. This project follows phase-based delivery.
+
+## [Unreleased]
+
+### Local Integration Console (ADR-013)
+
+- **`veille` CLI**: `doctor`, `connections`, `workflows`, `run`, `runs`, `providers`, `adapters`, `demo`, `explore`, `serve` subcommands. Registered as `[project.scripts] veille` in `pyproject.toml`.
+- **Console backend** (`src/supervisor/console/`): `VeilleSettings` (VEILLE_* env namespace), `doctor_payload()`, `WorkflowInfo`/`AdapterInfo`/`ConnectionInfo` run registry, `explore()` multi-view projection over any `RunEventBatch`, `validate_connection()`, FastAPI server (`/api/health`, `/api/doctor`, `/api/connections`, `/api/workflows`, `/api/runs`, `/api/providers`, `/api/adapters`).
+- **Framework adapter ports** (`src/supervisor/adapters/ports.py`): `FrameworkAdapter` + `RunEventHook` protocols.
+- **Provider drivers** (`src/supervisor/adapters/providers/`): `ModelProvider` port + 8 concrete drivers (LiteLLM, OpenAI, Anthropic, Gemini, OpenRouter, Ollama, LM Studio, OpenAI-compatible). All default to mock; real mode gated behind `VEILLE_REAL_MODE=true`.
+- **Generic adapter** (`src/supervisor/adapters/generic.py`): wraps any callable into an `InstrumentedAgent`.
+- **OpenAI Agents SDK adapter** (`src/supervisor/adapters/openai_agents/`): skeleton with generic fallback.
+- **OpenAI Responses API adapter** (`src/supervisor/adapters/openai_responses/`): skeleton with generic fallback.
+- **SDK extensions**: `model()`/`tool()` accept optional `provider`, `prompt_version`; emit `provider`/`model`/`reuse_reason` attributes. `RoutingDecision` carries `provider` field. `_derive_provider()` maps model strings → provider identifiers.
+- **Run summary extensions**: `RunSummary` adds `providers`, `cache_reuse`, `policy_events`, `intervention_events`, `validation_checks`.
+- **Context diversification** (`src/supervisor/context/diversification.py`): `CompressionReport`/`DiversificationReport`, `compression_reports()`/`diversification_reports()` using `ShingleSemanticKey` + Jaccard.
+- **Router updates**: `_default()` seeds real model candidates (`gpt-4o`, `openrouter/gpt-4o`, `claude-3.5-sonnet`, `gemini-1.5-pro`, `ollama/llama3`, `lmstudio/local-model`) after mock candidates.
+- **React+TypeScript+Vite web UI** (`ui/`): 6 pages (Overview, Workflows, Run Explorer, Connections, Adapters, Policies) consuming FastAPI endpoints.
+- **`ui` optional dependency**: `fastapi`, `uvicorn`, `pydantic-settings` for the web server.
+- **Registered workflows**: `cited_market_research` (mock, langgraph), `real_world_demo` (real-capable, sdk), `langgraph_demo` (mock, langgraph with normalized events).
+- Tests: 34 new console tests (config, providers, adapters, explorer, connections); 165 total passing.
+
+### Approved cache policy (post-0.2.0, ADR-012)
+
+- **`supervisor/optimize/policy.py`**: `CachePolicy` + `build_cache_key` encode the
+  three partner-validated cache rules. `search_competitors` is cacheable only for
+  **identical normalized inputs** (exact); semantic/near-duplicate matches are
+  recommended, never served. Cache keys include **tenant/project, tool version,
+  policy version, and authorization/context boundaries**. Default **300s TTL**;
+  expired/uncertain results re-execute. Serving is gated behind partner
+  confirmation (`SUPERVISOR_CACHE_APPROVED` override or `SUPERVISOR_CACHE_CONFIRMATIONS >= 3`).
+- **SDK wiring** (`src/supervisor/sdk/supervisor.py`): `tool()`/`model()` serve only
+  when approved, allowlisted, idempotent, and exact; composite key + TTL applied.
+- **Adaptive rerouting remains advisory-only** (unchanged).
+- Tests: `tests/sdk/test_cache_policy.py` (6 rules/gate tests); 125 total passing.
+
+### Cross-run (durable) caching
+
+- **`supervisor/optimize/cache.py`**: new pluggable `CacheBackend` (port) with an
+  in-memory `InMemoryCache` (per-run) and a durable `FileCacheBackend` (JSON on
+  disk, wall-clock TTL, tenant-scoped by the composite key). `make_backend(...)`
+  constructs by kind (`memory`|`file`).
+- **SDK wiring** (`src/supervisor/sdk/supervisor.py`): `Supervisor` accepts a
+  `cache_backend` and selects `FileCacheBackend` when `SUPERVISOR_CACHE_BACKEND=file`
+  (`SUPERVISOR_CACHE_DIR`). Cross-run cache lookup is by exact composite key and is
+  independent of the in-run dedup detector, so a fresh `Supervisor` still reads
+  prior runs' cached results (and the same approved `CachePolicy` gates serving).
+- **Real-world demo** (`examples/real_world_demo`): `--cross-run` flag shares a
+  durable backend across two runs; under approval the second run serves all
+  identical searches (cost $0.008 → $0.004). Tests: `tests/sdk/test_file_cache.py`.
+- 131 total passing (ruff + mypy clean).
+
+## [0.2.0] — Phases 1–5 (2026-07-14)
+
+### Phase 5 — Memory lifecycle & retrieval governance (implemented)
+
+- **Memory store** (`src/supervisor/memory/store.py`): `MemoryBackend` port + `InMemoryMemoryStore` (tenant-isolated, no deps); `MemoryRecord` with tier (working/short/long/archive), provenance, confidence, TTL, and baseline hash for drift; `content_hash` util. Mem0/Letta/customer RAG attach behind the port.
+- **Scoring** (`src/supervisor/memory/scoring.py`): `score(record, now, role_weights)` combines recency (exponential decay), usage, provenance quality, and confidence; metadata-driven, no embeddings by default. `default_role_weights` nudge tier preference by role.
+- **Governor** (`src/supervisor/memory/governor.py`): `MemoryManifest` + `MemoryGovernor.retrieve(...)` scores candidates, flags `stale` (recency/confidence) and `drift` (content hash vs baseline), and emits an included/excluded/stale/drift/scores/reason manifest. `expire_due(...)` surfaces TTL-elapsed records for **audited** removal — no automatic deletion.
+- **Event schema 0.2.0 (additive):** `memory.retrieved` carries the governance manifest; new `memory.expired` records expiry candidates and explicit removals.
+- **SDK wiring** (`src/supervisor/sdk/supervisor.py`): `Supervisor.remember`, `retrieve_memory`, `expire_memory`, `forget_memory`; gated by `SUPERVISOR_MEMORY=1`. Off-mode `retrieve_memory` is a no-op passthrough (identical to Phase 4).
+- **Run summary** (`src/supervisor/analytics/run_summary.py`): `memories_retrieved`, `memories_stale`, `memories_drift`, `memories_expired`.
+- **Demo:** researcher node stores a working memory and retrieves it on subsequent calls when `SUPERVISOR_MEMORY=1`.
+- **Tests:** store, scoring, governor, SDK memory, demo memory — 119 total.
+- **Docs:** ADR-011 (memory governance), data-contracts / architecture / runtime-chain / integrations / operations / roadmap / README updates.
+
+### Phase 4 — Semantic dedup and adaptive caching (implemented)
+
+- **Semantic key** (`src/supervisor/optimize/keys.py`): `ShingleSemanticKey` tokenizes input into word-shingles and compares with Jaccard similarity (default threshold 0.85). Embedding backend is a future `SemanticKey` port.
+- **Near-duplicate detector** (`src/supervisor/optimize/dedup.py`): `DuplicateDetector` returns `DuplicateMatch` (`exact` | `semantic`, `similarity`, `cache_key`) for in-run `(tool, input)` calls.
+- **Cache backend** (`src/supervisor/optimize/cache.py`): `CacheBackend` port with `InMemoryCache` (bounded LRU-ish FIFO + per-entry TTL). Redis is a later backend behind the same port.
+- **Event schema 0.2.0** (`src/supervisor/contracts/events.py`): new `optimization.recommended` / `optimization.applied`; `tool.requested` / `model.requested` gain `match_type` + `similarity`; `optimization.*` carry `cache_key`, `cache_hit`, `estimated_savings_usd`. Additive over 0.1.0.
+- **SDK wiring** (`src/supervisor/sdk/supervisor.py`): `Supervisor.tool(idempotent=)` / `model(cacheable=)` consult detector + cache. Dry-run recommends; active serves idempotent cache hits and skips re-execution. Gated by `SUPERVISOR_OPTIMIZE` (`dry_run` default, `SUPERVISOR_OPTIMIZE_MODE=active`).
+- **Run summary** (`src/supervisor/analytics/run_summary.py`): `cache_hits`, `cache_served`, `semantic_duplicates`, `estimated_savings_usd`.
+- **Demo:** idempotent tool calls are cached when optimization is enabled; expensive scenario serves the duplicate `search_competitors` from cache in active mode.
+- **Tests:** keys, dedup, cache, SDK dry-run/active, demo optimization — 99 total.
+- **Docs:** ADR-010 (semantic dedup + caching + dry-run opt-in), data-contracts / architecture / runtime-chain / integrations / operations / roadmap / README updates.
+
+### Phase 3 — Planner, context, routing (implemented)
+
+- **Plan tiers** (`src/supervisor/contracts/plan.py`): `PlanTier` (minimum / balanced /
+  high_quality / maximum_assurance), `TierEstimate`, `PlanStep`, `ExecutionPlan`.
+- **Planner** (`src/supervisor/planning/planner.py`): deterministic `select_tier(task)`
+  (risk baseline, cost bump, critical clamp) and `Planner.build_plan` → `ExecutionPlan`
+  with tier options (cost/latency multipliers) and steps; one option marked `recommended`.
+- **Context engine** (`src/supervisor/context/engine.py`): `ContextEngine.build_manifest`
+  builds a role-sensitive `ContextManifest` (included / excluded / compressed slices +
+  estimated tokens) deterministically from a master context.
+- **Model routing** (`src/supervisor/routing/router.py`): `ModelRegistry` + `ModelRouter.select`
+  returns a tier-aware `RoutingDecision` (capability + tier + allowed_models; deterministic;
+  safe static fallback for empty registries).
+- **SDK wiring** (`src/supervisor/sdk/supervisor.py`): `Supervisor.plan()`, `route_model()`,
+  `model(routing=)`, `context(master_context=)`; `start_run` records the planned `tier`.
+- **Run summary** (`src/supervisor/analytics/run_summary.py`): `RunSummary.plan_tier` and
+  `routing[]` derived from routed `model.requested` events (`routing_tier` /
+  `routing_capability` / `routing_reason`).
+- **Advisory by default:** gated behind `SUPERVISOR_PLAN=1` (mirroring `SUPERVISOR_ENFORCE`);
+  never blocks or rewrites execution.
+- **Demo:** `examples/cited_market_research/agent.py` wires researcher/analyst/writer through
+  the planner, router, and context engine when `SUPERVISOR_PLAN=1`.
+- **Tests:** planning, context, routing, SDK integration — 79 total.
+- **Docs:** ADR-008 (tier/cost model), ADR-009 (routing), data-contracts / architecture /
+  runtime-chain / integrations / operations / roadmap / README updates.
+
+### Phase 2 — Deterministic protection (implemented)
+
+- **Enforcement engine** (`src/supervisor/policy/enforcement.py`): `Enforcer` +
+  `GuardDecision`; exceptions `InterventionError` / `StopRun` / `PauseForApproval` /
+  `BlockedByPolicy`. Detection (`evaluate`) separated from action.
+- **Deterministic policies** (`src/supervisor/policy/engine.py`): `duplicate_tool_protection`
+  (block/dedupe), `retry_budget` (stop), `cost_budget` (stop), `stall_protection` (stop),
+  `loop_protection` (stop). Default mode `enforce`; gated by `Supervisor(enforce=True)`
+  or `SUPERVISOR_ENFORCE=true`.
+- **Budgets** (`src/supervisor/policy/budgets.py`): `BudgetTracker` behind a
+  `CounterBackend` port (in-memory default, Redis optional).
+- **SDK guards** (`src/supervisor/sdk/supervisor.py`): `tool()` dedupes blocked duplicates,
+  `retry()` stops on budget exhaustion; `emit_intervention` / `consult` / `act` helpers.
+- **Audit:** every action emits `intervention.applied` with `action`, `policy_id`, `reason`,
+  and `human_review_required`.
+- **Safe default:** observe mode is byte-for-byte identical to Phase 1.
+- **Demo:** opt-in enforcement via `SUPERVISOR_ENFORCE`; the expensive scenario is stopped
+  on retry-budget exhaustion.
+- **Tests:** policy evaluate, enforcement, budgets, SDK enforcement, adapter — 60 total.
+- **Docs:** ADR-006 (enforcement model), ADR-007 (budget backend), policy-engine /
+  data-contracts / roadmap updates.
+
+### Phase 1 — Observe and explain (implemented)
+
+- **Python SDK** (`src/supervisor/sdk/`): `Supervisor` emission helpers
+  (`start_run`, `finish_run`, `model`, `tool`, `retry`, `context`, `node`,
+  `emit_validation`) and `RunCollector` aggregation.
+- **LangGraph adapter** (`src/supervisor/adapters/langgraph/adapter.py`): callback-based
+  automatic instrumentation; agent authors call `adapter.attach(graph)` only.
+- **Run summary analytics** (`src/supervisor/analytics/run_summary.py`): `summarize()`
+  produces a `RunSummary` (tool call counts, duplicates, retries, cost, timeline,
+  policy observations, validation result).
+- **Observe-only policy engine** (`src/supervisor/policy/engine.py`): `evaluate_observe`
+  detects duplicate tool calls, retry storms (budget 5), cost overruns, and validation
+  failures; emits `policy.triggered` events. Never alters execution.
+- **OTel exporter** (`src/supervisor/telemetry/exporter.py`): `ConsoleOTelExporter`
+  (default) and `OtlpExporter` (OTLP/gRPC) via `event_to_span`.
+- **Run-explorer CLI** (`src/supervisor/cli.py`): `explore` subcommand for fixtures
+  (`--run`) or live runs (`--live --scenario`) with `--policy` and `--otel` flags.
+- **Demo refactor** (`examples/cited_market_research/agent.py`): now uses the SDK;
+  `trace_capture.py` reduced to `validate_brief` input validation only.
+- **Tests:** sdk, analytics, policy, telemetry mapping, langgraph adapter, cli, and
+  demo smoke — 39 tests passing.
+- **Docs:** ADR-004 (LangGraph callbacks), ADR-005 (OTel mapping), event attributes
+  registry in `data-contracts.md`, updated architecture/runtime-chain/policy-engine/
+  integrations/operations/roadmap.
+- **Quality gates:** `ruff`, `mypy --strict`, `pytest` all green on Python 3.14.
+
+## [0.1.0] — Phase 0 baseline (2026-07-14)
+
+- Data contracts v0.1: task contract, run events, validation report.
+- Adapter ports: LangGraph (interface), LiteLLM mock, OTel interface.
+- Synthetic cited market-research LangGraph workflow.
+- Trace fixtures (success, expensive, failed_validation).
+- Documentation system, docker compose, CI, dev scripts.

veille_supervisor-0.3.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: veille-supervisor
+Version: 0.3.0
+Summary: Control plane for production AI-agent work: plan, govern, and verify agent runs.
+Project-URL: Homepage, https://github.com/Raphel6969/Veille
+Project-URL: Repository, https://github.com/Raphel6969/Veille
+Project-URL: Documentation, https://github.com/Raphel6969/Veille/tree/main/docs
+Project-URL: Issues, https://github.com/Raphel6969/Veille/issues
+Author: AI Runtime Supervisor Team
+License: MIT
+Keywords: agents,ai,control-plane,llm,observability,supervisor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: langchain-core<1,>=0.3
+Requires-Dist: langgraph<1,>=0.2
+Requires-Dist: pydantic-settings<3,>=2.6
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Requires-Dist: types-pyyaml<7,>=6.0; extra == 'dev'
+Provides-Extra: litellm
+Requires-Dist: litellm<2,>=1.55; extra == 'litellm'
+Provides-Extra: ui
+Requires-Dist: fastapi<1,>=0.110; extra == 'ui'
+Requires-Dist: uvicorn<1,>=0.30; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# AI Runtime Supervisor / Veille Console
+
+Control plane for production AI-agent work. The Supervisor plans, contextualizes, routes, governs, and verifies each agent run—reducing wasted spend and unreliable outcomes without requiring teams to rebuild their applications.
+
+**Current release:** [0.2.0](docs/release-notes/0.2.0.md) — Phases 1–5 + **Local Integration Console**. Event schema `0.2.0`. All capabilities are opt-in and off by default.
+
+## What exists today
+
+- Versioned data contracts (task, events, plan, policy, validation)
+- Python SDK (`Supervisor` + `RunCollector`) for zero-touch event emission
+- LangGraph adapter with automatic callback-based instrumentation
+- **OpenAI Agents SDK adapter** and **OpenAI Responses API adapter** (skeleton)
+- **Model provider port** with 8 provider drivers (LiteLLM, OpenAI, Anthropic, Gemini, OpenRouter, Ollama, LM Studio, OpenAI-compatible)
+- Synthetic cited market-research LangGraph demo workflow with mock tools
+- Representative trace fixtures for success, expensive, and failed-validation runs
+- Observe-only policy engine (duplicate detection, retry budget, cost overrun, validation)
+- **Opt-in enforcement** (Phase 2): block / retry / pause / stop with full audit trail
+- Budget tracking (`BudgetTracker`, in-memory default, Redis backend port)
+- Run-explorer CLI and OpenTelemetry export (Console + OTLP)
+- **Advisory planning** (Phase 3): tier selection, per-step context manifests, capability+tier model routing
+- **Adaptive optimization** (Phase 4): semantic near-duplicate detection + idempotent result caching (`SUPERVISOR_OPTIMIZE`, dry-run default)
+- **Memory governance** (Phase 5): memory store + scoring + governor (`memory.retrieved`/`memory.expired` manifest) with audited expiry, no automatic deletion (`SUPERVISOR_MEMORY`)
+- **Local Integration Console** (`veille` CLI + FastAPI + React web UI) — register workflows, connect providers, run live, inspect execution
+- Local development environment (Docker Compose + pytest)
+
+## Quickstart
+
+### Prerequisites
+
+- Python 3.12+
+- Docker Desktop (optional, for Postgres/Redis/MinIO scaffold)
+
+### Setup (Windows)
+
+```powershell
+.\scripts\dev.ps1
+.\.venv\Scripts\Activate.ps1
+```
+
+### Run tests
+
+```powershell
+pytest -v
+```
+
+### Use the console
+
+```powershell
+# Doctor — environment + safe-config report
+veille doctor
+
+# List provider connections
+veille connections
+veille connections validate openai
+
+# List registered workflows
+veille workflows
+
+# Run the mock demo
+veille demo mock
+
+# Run the real-world demo
+veille demo real-world
+
+# List saved runs
+veille runs
+
+# Run an arbitrary registered workflow
+veille run cited_market_research --input '{"scenario":"success"}'
+
+# Start the web UI (then open http://127.0.0.1:8000)
+veille serve
+```
+
+### Run the classic demo workflow
+
+```powershell
+# Successful run
+python -m examples.cited_market_research.agent --scenario success
+
+# All scenarios + write trace fixtures
+python -m examples.cited_market_research.agent --scenario all --write-fixtures
+
+# Phase 1 run explorer (inspect a captured run)
+python -m supervisor.cli explore --run fixtures/traces/expensive_run.json --policy
+
+# Live run with policy observations and OTel export
+python -m supervisor.cli explore --live --scenario expensive --policy --otel
+```
+
+No API keys required. Mock models and tools are used by default.
+
+## Repository layout
+
+```text
+src/supervisor/          Core contracts, SDK, adapters, analytics, policy, telemetry, CLI, console
+examples/                Runnable demo workflows
+fixtures/traces/         Synthetic trace JSON for tests and baselines
+docs/                    Architecture, contracts, roadmap, ADRs
+docs/development/        Source master prompt, blueprint, phase plans
+ui/                      React+TypeScript+Vite web UI (veille console frontend)
+templates/               Baseline measurement templates
+```
+
+## Documentation
+
+| Document | Description |
+|---|---|
+| [Architecture](docs/architecture.md) | System components and boundaries |
+| [Runtime chain](docs/runtime-chain.md) | Stage-by-stage runtime flow |
+| [Data contracts](docs/data-contracts.md) | Schema reference |
+| [Roadmap](docs/roadmap.md) | Phase status and deferrals |
+| [Integrations](docs/integrations.md) | Adapter contracts + provider drivers |
+| [Operations](docs/operations.md) | Local dev, commands, runbooks |
+| [Policy engine](docs/policy-engine.md) | Policy modes and Phase 1 observe policies |
+| [ADR-013](docs/adr/013-local-integration-console.md) | Local Integration Console design |
+
+### Setup guides
+
+| Guide | Description |
+|---|---|
+| [Safe local setup](docs/guides/safe-local-setup.md) | Running with mock providers (default) |
+| [Mock demo walkthrough](docs/guides/mock-demo.md) | End-to-end mock demo |
+| [Real provider setup](docs/guides/real-provider-setup.md) | Setting up real model providers |
+| [OpenRouter integration](docs/guides/openrouter-setup.md) | Using OpenRouter as a gateway |
+| [OpenAI Agents SDK](docs/guides/openai-agents-sdk.md) | Running an OpenAI Agents SDK workflow |
+| [LiteLLM integration](docs/guides/litellm-integration.md) | Using LiteLLM for multi-provider access |
+
+## License
+
+MIT

veille_supervisor-0.3.0/README.md

@@ -0,0 +1,131 @@
+# AI Runtime Supervisor / Veille Console
+
+Control plane for production AI-agent work. The Supervisor plans, contextualizes, routes, governs, and verifies each agent run—reducing wasted spend and unreliable outcomes without requiring teams to rebuild their applications.
+
+**Current release:** [0.2.0](docs/release-notes/0.2.0.md) — Phases 1–5 + **Local Integration Console**. Event schema `0.2.0`. All capabilities are opt-in and off by default.
+
+## What exists today
+
+- Versioned data contracts (task, events, plan, policy, validation)
+- Python SDK (`Supervisor` + `RunCollector`) for zero-touch event emission
+- LangGraph adapter with automatic callback-based instrumentation
+- **OpenAI Agents SDK adapter** and **OpenAI Responses API adapter** (skeleton)
+- **Model provider port** with 8 provider drivers (LiteLLM, OpenAI, Anthropic, Gemini, OpenRouter, Ollama, LM Studio, OpenAI-compatible)
+- Synthetic cited market-research LangGraph demo workflow with mock tools
+- Representative trace fixtures for success, expensive, and failed-validation runs
+- Observe-only policy engine (duplicate detection, retry budget, cost overrun, validation)
+- **Opt-in enforcement** (Phase 2): block / retry / pause / stop with full audit trail
+- Budget tracking (`BudgetTracker`, in-memory default, Redis backend port)
+- Run-explorer CLI and OpenTelemetry export (Console + OTLP)
+- **Advisory planning** (Phase 3): tier selection, per-step context manifests, capability+tier model routing
+- **Adaptive optimization** (Phase 4): semantic near-duplicate detection + idempotent result caching (`SUPERVISOR_OPTIMIZE`, dry-run default)
+- **Memory governance** (Phase 5): memory store + scoring + governor (`memory.retrieved`/`memory.expired` manifest) with audited expiry, no automatic deletion (`SUPERVISOR_MEMORY`)
+- **Local Integration Console** (`veille` CLI + FastAPI + React web UI) — register workflows, connect providers, run live, inspect execution
+- Local development environment (Docker Compose + pytest)
+
+## Quickstart
+
+### Prerequisites
+
+- Python 3.12+
+- Docker Desktop (optional, for Postgres/Redis/MinIO scaffold)
+
+### Setup (Windows)
+
+```powershell
+.\scripts\dev.ps1
+.\.venv\Scripts\Activate.ps1
+```
+
+### Run tests
+
+```powershell
+pytest -v
+```
+
+### Use the console
+
+```powershell
+# Doctor — environment + safe-config report
+veille doctor
+
+# List provider connections
+veille connections
+veille connections validate openai
+
+# List registered workflows
+veille workflows
+
+# Run the mock demo
+veille demo mock
+
+# Run the real-world demo
+veille demo real-world
+
+# List saved runs
+veille runs
+
+# Run an arbitrary registered workflow
+veille run cited_market_research --input '{"scenario":"success"}'
+
+# Start the web UI (then open http://127.0.0.1:8000)
+veille serve
+```
+
+### Run the classic demo workflow
+
+```powershell
+# Successful run
+python -m examples.cited_market_research.agent --scenario success
+
+# All scenarios + write trace fixtures
+python -m examples.cited_market_research.agent --scenario all --write-fixtures
+
+# Phase 1 run explorer (inspect a captured run)
+python -m supervisor.cli explore --run fixtures/traces/expensive_run.json --policy
+
+# Live run with policy observations and OTel export
+python -m supervisor.cli explore --live --scenario expensive --policy --otel
+```
+
+No API keys required. Mock models and tools are used by default.
+
+## Repository layout
+
+```text
+src/supervisor/          Core contracts, SDK, adapters, analytics, policy, telemetry, CLI, console
+examples/                Runnable demo workflows
+fixtures/traces/         Synthetic trace JSON for tests and baselines
+docs/                    Architecture, contracts, roadmap, ADRs
+docs/development/        Source master prompt, blueprint, phase plans
+ui/                      React+TypeScript+Vite web UI (veille console frontend)
+templates/               Baseline measurement templates
+```
+
+## Documentation
+
+| Document | Description |
+|---|---|
+| [Architecture](docs/architecture.md) | System components and boundaries |
+| [Runtime chain](docs/runtime-chain.md) | Stage-by-stage runtime flow |
+| [Data contracts](docs/data-contracts.md) | Schema reference |
+| [Roadmap](docs/roadmap.md) | Phase status and deferrals |
+| [Integrations](docs/integrations.md) | Adapter contracts + provider drivers |
+| [Operations](docs/operations.md) | Local dev, commands, runbooks |
+| [Policy engine](docs/policy-engine.md) | Policy modes and Phase 1 observe policies |
+| [ADR-013](docs/adr/013-local-integration-console.md) | Local Integration Console design |
+
+### Setup guides
+
+| Guide | Description |
+|---|---|
+| [Safe local setup](docs/guides/safe-local-setup.md) | Running with mock providers (default) |
+| [Mock demo walkthrough](docs/guides/mock-demo.md) | End-to-end mock demo |
+| [Real provider setup](docs/guides/real-provider-setup.md) | Setting up real model providers |
+| [OpenRouter integration](docs/guides/openrouter-setup.md) | Using OpenRouter as a gateway |
+| [OpenAI Agents SDK](docs/guides/openai-agents-sdk.md) | Running an OpenAI Agents SDK workflow |
+| [LiteLLM integration](docs/guides/litellm-integration.md) | Using LiteLLM for multi-provider access |
+
+## License
+
+MIT

veille_supervisor-0.3.0/docker-compose.yml

@@ -0,0 +1,47 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: supervisor
+      POSTGRES_PASSWORD: supervisor_dev
+      POSTGRES_DB: supervisor
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U supervisor -d supervisor"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  minio:
+    image: minio/minio:latest
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+  minio_data: