Metadata-Version: 2.4
Name: agentorch
Version: 1.0.0
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: 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

```bash
# 1. Install
pip install agentorch

# 2. Go to your project
cd /path/to/your/project

# 3. One-command setup (choose your IDE)
devtorch setup                       # Claude Code (default)
devtorch setup --target cursor       # Cursor
devtorch setup --target antigravity  # Google Antigravity

# 4. Verify
devtorch doctor
```

The setup command initializes `.GCC/` in your project, writes the MCP server config for your IDE, and adds DevTorch instructions to `CLAUDE.md` / `AGENTS.md`.

### IDE support

| IDE | Integration | Status |
|-----|-------------|--------|
| Claude Code | MCP server + hooks + CLAUDE.md | ✓ `devtorch setup` |
| Cursor | MCP server + VS Code extension | ✓ `devtorch setup --target cursor` |
| Google Antigravity | MCP server + AGENTS.md | ✓ `devtorch setup --target antigravity` |
| VS Code | Sidebar extension (.vsix) | ✓ Manual — see IDE_SETUP.md |
| JetBrains (IntelliJ/PyCharm) | Plugin | Coming soon |
| OpenAI Codex CLI | HTTP proxy | ✓ See CODEX_SETUP.md |

---

## Quick start

```bash
cd /path/to/your/project
devtorch init

# Record reasoning commits
devtorch commit -m "Chose idempotent transfer endpoint design"

# Add per-agent branches
devtorch branch app
devtorch branch dba
devtorch branch security-review

# Add sensitivity information
devtorch sensitivity add \
  --source agent-app \
  --concept api_contract \
  --confidence 0.9 \
  --disclosure PUBLIC \
  -m "API shape depends on transaction schema"

# Inspect state
devtorch status
devtorch debug timeline
devtorch debug branch-compare app dba
```

---

## 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
