Metadata-Version: 2.4
Name: agentorch
Version: 1.1.1
Summary: DevTorch — AI reasoning capture, audit trail, and governance for agent-assisted development
Author-email: Hemant Joshi <hemant@flotorch.ai>
License: Apache-2.0
Project-URL: Homepage, https://github.com/hemantcgi/DevTorch
Project-URL: Repository, https://github.com/hemantcgi/DevTorch
Project-URL: Documentation, https://github.com/hemantcgi/DevTorch/blob/main/Implementation/README.md
Keywords: ai,agents,governance,audit,llm,reasoning,devtorch
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: boto3>=1.34.0; extra == "dev"
Provides-Extra: wrapper
Requires-Dist: anthropic>=0.40.0; extra == "wrapper"
Requires-Dist: openai>=1.50.0; extra == "wrapper"
Requires-Dist: google-generativeai>=0.8.0; extra == "wrapper"
Requires-Dist: boto3>=1.35.0; extra == "wrapper"
Requires-Dist: tiktoken>=0.7.0; extra == "wrapper"
Provides-Extra: proxy
Requires-Dist: fastapi>=0.115.0; extra == "proxy"
Requires-Dist: uvicorn[standard]>=0.32.0; extra == "proxy"
Requires-Dist: httpx>=0.27.0; extra == "proxy"
Requires-Dist: pydantic>=2.9.0; extra == "proxy"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: cloud
Requires-Dist: fastapi>=0.111.0; extra == "cloud"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "cloud"
Requires-Dist: boto3>=1.34.0; extra == "cloud"
Requires-Dist: PyJWT>=2.8.0; extra == "cloud"
Requires-Dist: cryptography>=42.0.0; extra == "cloud"
Requires-Dist: PyNaCl>=1.5.0; extra == "cloud"
Provides-Extra: broadcast
Requires-Dist: watchdog>=3.0.0; extra == "broadcast"
Provides-Extra: all
Requires-Dist: agentorch[cloud,mcp,proxy,wrapper]; extra == "all"

# DevTorch

**Local-first AI agent governance.** DevTorch gives multi-agent systems a shared on-disk audit trail, coordination vector, privacy controls, and LLM integration layer — all without a remote service.

```bash
pip install agentorch
devtorch init
devtorch setup          # connects to Claude Code, Cursor, or Antigravity
devtorch debug timeline
```

---

## What it does

| Concern | DevTorch feature |
|---------|-----------------|
| Reasoning audit trail | Append-only `.GCC/events.log.jsonl` with SHA-256 hash chain |
| Multi-agent coordination | Coordination vector Θ — shared sensitivity map across agents |
| Privacy compliance | RDP ε-budget tracking; `[PRIVATE]` span suppression; SIS-TC quarantine |
| LLM integration | SDK wrappers, HTTP proxy, Claude Code MCP server + hooks |
| Governance observability | Structured reports, browser dashboard, VS Code extension (Antigravity-compatible) |
| Alerting | Slack, Jira, PagerDuty outbound webhooks |
| Metrics | MCS, DHS, ROI — all traceable to citations or explicit design choices |

Everything lives in `.GCC/` — a local directory in your project. No database, no network service, no telemetry.

---

## Install

```bash
pip install agentorch
```

**Requirements:** Python 3.10+

For optional extras:

```bash
pip install agentorch[wrapper]   # SDK wrappers (Anthropic, OpenAI, Gemini, Bedrock, Ollama)
pip install agentorch[proxy]     # HTTP proxy + dashboard API (FastAPI)
pip install agentorch[all]       # everything
```

> The PyPI package is named `agentorch`. The CLI command and import paths remain `devtorch` / `devtorch_core`.

---

## Getting Started

DevTorch takes **5 minutes to set up**. Pick your AI coding tool below.

> **Prerequisites:** Python 3.10+, pip, and the AI tool you plan to use.

---

### Claude Code

Claude Code is the highest-fidelity integration — hooks fire on every file write, MCP tools give Claude native governance commands, and `CLAUDE.md` carries persistent instructions across sessions.

**Step 1 — Install DevTorch**
```bash
pip install agentorch
```

**Step 2 — Go to your project and run setup**
```bash
cd /path/to/your/project
devtorch setup
```

This single command:
- Initialises `.GCC/` (the local governance store)
- Writes `.claude/hooks.json` so hooks fire on every Write, Edit, Bash, and Stop event
- Adds the DevTorch MCP server to `.claude/settings.json`
- Writes governance instructions into `CLAUDE.md`

**Step 3 — Verify**
```bash
devtorch doctor
```

Expected output: all checks green. If any check fails, the doctor output tells you exactly what to fix.

**Step 4 — Start using Claude Code**

Open Claude Code in your project. On the first task Claude will call `devtorch_context` to load prior reasoning, and `devtorch_commit` before any file edit. The `.GCC/` store captures everything automatically.

**What you get:** Full RACP integration — reasoning commits, sensitivity events, coordination vector Θ, divergence detection, HITL conflict resolution.

---

### Cursor

Cursor is a VS Code fork with native MCP support. DevTorch integrates via MCP tools and the VS Code sidebar extension.

**Step 1 — Install DevTorch**
```bash
pip install agentorch
```

**Step 2 — Run setup**
```bash
cd /path/to/your/project
devtorch setup --target cursor
```

This creates `.cursor/mcp.json` wiring the DevTorch MCP server into Cursor, initialises `.GCC/`, and writes `CLAUDE.md` with governance instructions.

**Step 3 — Add Cursor rules**

Create `.cursor/rules/devtorch.mdc`:
```
---
alwaysApply: true
---
Before any file edit, call devtorch_commit with your reasoning and the concepts you are touching.
Call devtorch_context at the start of each task to load prior decisions.
Call devtorch_sensitivity_add when touching auth, payments, schema, secrets, or PII.
```

**Step 4 — Install the VS Code extension (optional but recommended)**

In Cursor: `Cmd+Shift+P` → "Extensions: Install from VSIX" → select `extensions/vscode/devtorch-0.1.0.vsix` from the DevTorch source directory. This adds a live sidebar panel showing `.GCC/` state, Θ hot zones, and the event feed.

**Step 5 — Verify**
```bash
devtorch doctor
```

**What you get:** MCP tools, VS Code sidebar, optional HTTP proxy for passive capture of all LLM calls (`devtorch proxy start`).

---

### Google Antigravity

Google Antigravity is a VS Code fork with a multi-agent orchestration layer. It reads `AGENTS.md` for persistent AI instructions and supports MCP servers.

**Step 1 — Install DevTorch**
```bash
pip install agentorch
```

**Step 2 — Run setup**
```bash
cd /path/to/your/project
devtorch setup --target antigravity
```

This initialises `.GCC/`, writes the DevTorch MCP server config for Antigravity, and writes governance instructions into `AGENTS.md`.

**Step 3 — Install the VS Code extension**

In Antigravity: `Cmd+Shift+P` → "Extensions: Install from VSIX" → select `extensions/vscode/devtorch-0.1.0.vsix`.

**Step 4 — Verify**
```bash
devtorch doctor
```

**What you get:** Full RACP integration. The multi-agent nature of Antigravity makes Θ accumulation especially valuable — multiple agents share the same reasoning state through `devtorch_context`.

---

### VS Code (with GitHub Copilot)

VS Code + Copilot has **partial integration only**. Copilot's API is closed — DevTorch cannot intercept completions or inject RACP context. What works: the sidebar panel showing `.GCC/` state, and git-commit-level capture via the git hook.

**Step 1 — Install DevTorch**
```bash
pip install agentorch
cd /path/to/your/project
devtorch init
devtorch hooks install
```

**Step 2 — Install the VS Code extension**

`Cmd+Shift+P` → "Extensions: Install from VSIX" → select `extensions/vscode/devtorch-0.1.0.vsix`.

The sidebar shows your branch, last commit, Θ hot zones, and the live event feed from `.GCC/`.

**Step 3 — Record reasoning manually**

Since Copilot's internal reasoning cannot be captured automatically, record your own reasoning commits:
```bash
devtorch commit -m "Chose JWT over sessions — stateless service, no session store needed"
devtorch sensitivity add --source you --concept auth --confidence 0.9 --disclosure PROTECTED -m "Token expiry logic is security-critical"
```

**What you get:** Sidebar panel (read-only), git-commit-level event capture, manual reasoning commits. Full capture requires switching to Claude Code, Cursor, Kiro, or Antigravity.

---

### AWS Kiro

Kiro is Amazon's AI IDE. It uses steering documents and hooks — analogous to `CLAUDE.md` and `hooks.json`. Full DevTorch integration is available via manual configuration.

**Step 1 — Install DevTorch**
```bash
pip install agentorch
cd /path/to/your/project
devtorch init
```

**Step 2 — Add the MCP server**

Create `.kiro/settings/mcp.json`:
```json
{
  "mcpServers": {
    "devtorch": {
      "command": "/absolute/path/to/.venv/bin/devtorch",
      "args": ["mcp-server"],
      "env": {}
    }
  }
}
```

Replace `/absolute/path/to/.venv/bin/devtorch` with the output of `which devtorch`.

**Step 3 — Add steering document**

Create `.kiro/steering/devtorch.md` with `inclusion: always`:
```markdown
---
inclusion: always
---

# DevTorch Governance

Before any file edit, call `devtorch_commit` with your reasoning and the concepts you are touching.
Call `devtorch_context` at the start of each task to load prior decisions.
Call `devtorch_sensitivity_add` when touching auth, payments, schema, secrets, or PII.
```

**Step 4 — Add agent hook**

Create `.kiro/hooks/devtorch-capture.md`:
```markdown
---
name: devtorch-capture
trigger: after-file-write
---
Run: devtorch hooks run post-tool-use
```

**Step 5 — Verify**
```bash
devtorch doctor
```

**What you get:** Full RACP integration equivalent to Claude Code — MCP tools, steering-document governance, agent action hooks.

---

### AWS Bedrock (Python SDK)

DevTorch integrates at the `boto3` call level with a one-line change.

**Step 1 — Install**
```bash
pip install agentorch[wrapper] boto3
cd /path/to/your/project
devtorch init
```

**Step 2 — Wrap your Bedrock client**
```python
# Before
import boto3
client = boto3.client("bedrock-runtime", region_name="us-east-1")

# After — one import change, same API
from devtorch_core.wrapper.bedrock import DevTorchBedrock
client = DevTorchBedrock(region_name="us-east-1")
```

All `invoke_model()` and `converse()` calls are identical. DevTorch injects the RACP system prefix and captures responses automatically.

**Step 3 — Verify**
```bash
devtorch doctor
```

---

### Azure AI Foundry (Python SDK)

**Step 1 — Install**
```bash
pip install agentorch[wrapper] openai
cd /path/to/your/project
devtorch init
```

**Step 2 — Wrap your Azure OpenAI client**
```python
# Before
from openai import AzureOpenAI

# After — one import change, all kwargs pass through unchanged
from devtorch_core.wrapper.openai import DevTorchOpenAI as AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://my-resource.openai.azure.com/",
    api_version="2024-02-01",
    api_key=os.environ["AZURE_OPENAI_KEY"],
)
# All chat.completions.create() calls are identical
```

**Step 3 — Verify**
```bash
devtorch doctor
```

---

### OpenAI Codex CLI

**Step 1 — Install**
```bash
pip install agentorch
cd /path/to/your/project
devtorch init
```

**Step 2 — Start the proxy**
```bash
devtorch proxy start   # runs on localhost:8765
```

**Step 3 — Point Codex at the proxy**
```bash
export OPENAI_BASE_URL=http://localhost:8765/v1
codex "Add error handling to the payment service"
```

All Codex calls are intercepted by the proxy, which injects the RACP prefix and captures responses into `.GCC/`.

---

### Ollama (local models)

**Step 1 — Install Ollama and pull a model**
```bash
# Install Ollama from https://ollama.com
ollama pull llama3.2
```

**Step 2 — Install DevTorch**
```bash
pip install agentorch[wrapper]
cd /path/to/your/project
devtorch init
```

**Step 3 — Wrap your Ollama client**
```python
from devtorch_core.wrapper.ollama import DevTorchOllama

client = DevTorchOllama(model="llama3.2")   # any model in `ollama list`
response = client.chat(messages=[{"role": "user", "content": "Explain this function"}])
```

**Step 4 — Verify**
```bash
devtorch doctor
```

No API key required. Fully local — RACP context and captures stay on-device.

---

### Platform comparison

| Platform | Setup command | MCP tools | Auto-capture | Sidebar | Notes |
|---|---|---|---|---|---|
| Claude Code | `devtorch setup` | ✅ | ✅ hooks | ✅ | Highest fidelity |
| Cursor | `devtorch setup --target cursor` | ✅ | ✅ proxy | ✅ | Near-full |
| Google Antigravity | `devtorch setup --target antigravity` | ✅ | ✅ | ✅ | Full |
| AWS Kiro | Manual (5 steps) | ✅ | ✅ hooks | ✅ | Full — not yet automated |
| VS Code + Copilot | `devtorch init` + extension | ❌ | ❌ git only | ✅ | Partial — Copilot API closed |
| AWS Bedrock | SDK wrapper | — | ✅ SDK | — | Python SDK only |
| Azure AI Foundry | SDK wrapper or proxy | — | ✅ SDK | — | Python SDK only |
| OpenAI Codex CLI | HTTP proxy | — | ✅ proxy | — | |
| Ollama | SDK wrapper | — | ✅ SDK | — | Fully local |

---

## LLM integration

### Option 1 — SDK wrapper (you own the code)

```python
# One-line change — same API, governance captured automatically
from devtorch_core.wrapper.anthropic import DevTorchAnthropic
client = DevTorchAnthropic()   # replaces anthropic.Anthropic()

# OpenAI
from devtorch_core.wrapper.openai import DevTorchOpenAI
client = DevTorchOpenAI()

# Local models via Ollama (no API key required)
from devtorch_core.wrapper.ollama import DevTorchOllama
client = DevTorchOllama(model="llama3.2")   # any model in `ollama list`

# Google Gemini
from devtorch_core.wrapper.gemini import DevTorchGemini
client = DevTorchGemini(model_name="gemini-1.5-pro")

# AWS Bedrock
from devtorch_core.wrapper.bedrock import DevTorchBedrock
client = DevTorchBedrock(region_name="us-east-1")
```

See `OLLAMA_SETUP.md` for the full Ollama guide.

### Option 2 — HTTP proxy (Cursor, JetBrains, closed-source IDEs)

```bash
devtorch proxy install   # installs as macOS LaunchAgent or Linux systemd service
devtorch proxy start     # runs on localhost:8765
```

Configure your IDE to use `http://localhost:8765/anthropic` (or `/openai`, `/gemini`). The proxy injects RACP context and captures responses with zero latency penalty.

### Option 3 — MCP server + hooks (Claude Code, Cursor, Kiro, Antigravity)

```bash
devtorch setup   # one command: init + hooks + MCP config + CLAUDE.md + AGENTS.md
```

Claude Code / Cursor / Kiro / Antigravity then call `devtorch_commit`, `devtorch_sensitivity_add`, `devtorch_context`, and `devtorch_theta_read` as native MCP tools. See `IDE_SETUP.md` for per-IDE instructions.

### Option 4 — OpenAI Codex CLI proxy

```bash
# Start the Codex-specific proxy on localhost:8766
python -m devtorch_core.codex start

# Point Codex CLI at it
export OPENAI_BASE_URL=http://localhost:8766/v1
codex "Add error handling to the payment service"
```

See `CODEX_SETUP.md` for the full guide.

### Option 5 — Org gateway (enterprise, multi-developer)

```bash
cd deploy/
cp .env.example .env   # set ANTHROPIC_API_KEY and/or OPENAI_API_KEY
docker compose up      # gateway on :8080, dashboard on :3000
```

Developers point their IDE proxy URL to the gateway instead of api.openai.com. The gateway handles central API key management, SSO attribution, governance policy enforcement, and metrics aggregation. See `deploy/README.md` for Helm and Docker Compose instructions.

---

## Architecture

```
devtorch_core/           Pure library — all business logic
  gcc.py                 GCCRepository: .GCC/ layout, event log, commits, branches
  sensitivity.py         Sensitivity events + SensitivityStore
  theta.py               Coordination vector Θ + AggPhi
  capability.py          OmegaCapability (A1), Lipschitz bound, PST runner
  invariants.py          I1 (commit-backed), I3 (semantic grounding)
  variance.py            f_max formula, rolling monitor, VARIANCE_ALERT
  rep.py                 REP ledger — append-only local transport
  sis.py                 SIS-TC corpus evaluation + quarantine
  rdp.py                 RDP ε-budget tracking
  disclosure.py          [PRIVATE] span suppression
  prompt_artifact.py     RACP system prompt artifact store
  deltaf.py              Δf estimation
  parser/                XML block extractor, thinking tokens, inference
  wrapper/               SDK drop-in wrappers (Anthropic, OpenAI, Gemini, Bedrock)
  proxy/                 HTTP reverse proxy (localhost:8765)
  mcp/                   MCP/JSON-RPC server
  hooks/                 Claude Code hooks + git commit-msg hook
  metrics/               MCS, DHS, ROI, calibration, citation registry
  observability/         Structured reports + enterprise metrics webhook
  alerts/                Slack, Jira, PagerDuty outbound alerting
  rep_network/           Multi-node REP ledger sync
  github/                GitHub App webhook + PR comment builder
  dashboard_api.py       REST API for browser dashboard

devtorch_cli/
  main.py                Thin argparse wrapper over devtorch_core

extensions/vscode/       VS Code extension (read-only sidebar; installs in Antigravity via .vsix)
dashboard/               React browser dashboard (Developer/Lead/CISO views)
tests/                   637 tests across all sprints (S0–S18)
examples/                end-to-end scenario examples
```

---

## On-disk layout (`.GCC/`)

```
.GCC/
  VERSION                    # format version
  events.log.jsonl           # append-only audit stream (hash chain)
  main.md / log.md           # reasoning roadmap + chronological log
  refs/HEAD                  # current branch
  refs/branches/<name>       # branch tip commit ID
  commits/<id>.json          # commit objects
  sensitivities/events.jsonl # raw sensitivity events
  theta.json                 # coordination vector Θ
  capabilities/omega.json    # A1 capability state
  variance/                  # calibration_report.json, live_state.json
  rep/rep_ledger.jsonl        # REP transport ledger
  rep/peers.json             # peer list for multi-node sync
  sis/                       # SIS-TC corpus, reports, quarantine events
  rdp/rdp_state.json         # RDP ε-budget
  concepts/<name>.json       # I3 concept definitions
  prompts/                   # RACP system prompt artifact
  deltaf/                    # Δf report
  calibration.json           # team-specific metric calibration
  context_bundles/           # MECW-bounded context snapshots
  NODE_STATE                 # node state machine
```

---

## Key safety properties

| Property | Mechanism |
|----------|-----------|
| Commit-backed decisions (I1) | Merge/unlock blocked unless branch tips exist in commits/ and events log |
| Semantic grounding (I3) | Operations using concepts_used require matching definitions in concepts/ |
| Capability gate (A1) | Textual mode requires valid OmegaCapability + passing PST |
| Variance control (A2) | f_max=0 forces deterministic mode; A1 gate blocks textual_mode |
| Privacy budget (RDP) | epsilon exhaustion flips read_only=true in rdp_state.json |
| Proxy trust boundary | Proxy binds to 127.0.0.1 only; API keys pass through, never stored |

---

## Run the tests

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e .[dev,proxy]
pytest tests/         # 637 tests
```

---

## Configuration reference

| Env var | Purpose |
|---------|---------|
| `DEVTORCH_DISABLE=1` | Disable all injection and capture (wrapper/proxy become transparent) |
| `DEVTORCH_SLACK_WEBHOOK_URL` | Slack alert delivery |
| `DEVTORCH_JIRA_URL` / `_PROJECT_KEY` / `_API_TOKEN` / `_EMAIL` | Jira issue creation |
| `DEVTORCH_PAGERDUTY_ROUTING_KEY` | PagerDuty event trigger |
| `DEVTORCH_ALERT_MIN_SEVERITY` | Minimum severity to alert on (`info`/`warning`/`critical`) |
| `DEVTORCH_METRICS_WEBHOOK_URL` | Enterprise metrics webhook endpoint |
| `DEVTORCH_ORG_ID` | Org identifier in metrics payloads |
| `DEVTORCH_METRICS_API_KEY` | Auth for metrics webhook |
| `DEVTORCH_GITHUB_WEBHOOK_SECRET` | HMAC secret for GitHub App webhook |

---

## Documentation

| File | Contents |
|------|----------|
| `DOCS.md` | Architecture deep-dive, Sprint 4–6 feature reference, conformance matrix |
| `OBSERVABILITY.md` | Observability pillars, daily-recall pattern, shell audit script template |
| `CONTRIBUTING.md` | Dev environment, test commands, sprint structure, PR checklist |
| `THREAT_MODEL.md` | Trust model, hash chain integrity, proxy trust boundary, known limitations |
| `DESIGN_THOUGHTS.md` | Design decisions Q1–Q14 with full citation validation |
| `IDE_SETUP.md` | VS Code, Cursor, Kiro, and Antigravity setup instructions |
| `ANTIGRAVITY_SETUP.md` | Google Antigravity step-by-step onboarding |
| `CLAUDE_CODE_QUICKSTART.md` | Claude Code step-by-step onboarding |
| `OLLAMA_SETUP.md` | Local model setup with Ollama (Llama, Mistral, Gemma, Phi, Qwen) |
| `CODEX_SETUP.md` | OpenAI Codex CLI proxy setup |
| `AGENTS.md` | Persistent AI instructions for Antigravity/Kiro |
| `deploy/README.md` | Enterprise org gateway — Docker Compose and Helm deployment |
| `devtorch_core/metrics/README.md` | MCS/DHS/ROI formulas and calibration guide |
| `devtorch_core/proxy/README.md` | HTTP proxy deployment options |
| `devtorch_core/wrapper/README.md` | SDK wrapper quick-start for all providers |
| `dashboard/README.md` | Browser dashboard setup and API reference |

---

## Metrics credibility

DevTorch is explicit about what every number is based on:

- **15 min context switch** — Parnin & Rugaber (2011), *Software Quality Journal*. DOI: [10.1007/s11219-010-9104-9](https://doi.org/10.1007/s11219-010-9104-9). Measured for programming tasks only.
- **Auditor rate** — BLS SOC 13-2011 (2023): $39–40/hr employed staff. External rates ($75–400/hr) not used as defaults.
- **MCS/DHS weights** — Design choices. No external benchmark. Calibrate with your team's data.
- **Developer hourly rate** — No default. You must set it: `devtorch calibrate --set developer_hourly_rate=<value>`

See `devtorch_core/metrics/credibility.py` for the full citation registry.

---

## License

Apache 2.0
