opencac 0.2.0__tar.gz

opencac-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lpoee976
+
+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.

opencac-0.2.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: opencac
+Version: 0.2.0
+Summary: OpenCAC: Claude Code, Antigravity, and Codex working together across cloud APIs and local models.
+Author: Codex
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lpoee/opencac
+Project-URL: Repository, https://github.com/lpoee/opencac
+Project-URL: Issues, https://github.com/lpoee/opencac/issues
+Keywords: opencac,claude-code,codex,antigravity,multi-agent-orchestration,ai-coding-agent-pipeline,claude-code-codex-together,ai-coding-workflow-automation,orchestrate-ai-coding-tools,developer-cli-tools,ai-agent-chaining,reduce-ai-api-cost,local-llm-code-quality,air-gapped-ai-coding,private-ai-code-generation,local-llm,hybrid-ai,jsonl,audit-log,speculative-decoding,llama-cpp,validated-handoff,session-resume
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# OpenCAC
+
+**OpenCAC is multi-agent orchestration CLI for AI coding tools. Wires Claude Code, Antigravity, and Codex into one pipeline with validated handoffs, audit logging, and speculative decoding for local LLMs.**
+
+```bash
+pip install .
+opencac run "refactor the auth module" --mode private
+```
+
+## Why
+
+For developers who already use multiple AI coding agents and want one CLI to orchestrate them — with cloud models, local LLMs, or both.
+
+```
+   - Claude Code, Codex, Antigravity powerful alone, but each runs in its own world
+   - Cloud api burns money — every hosted model call costs real tokens.
+   - Local LLMs lack quality — small models are cheap but can't reliably produce production-grade code.
+
+OpenCAC solves this by chaining agents into a four-role pipeline where each agent does what it's best at, with structured validation at every hop.
+```
+
+## Features
+
+```
+1. FOUR-ROLE PIPELINE
+   dispatcher → antigravity (research) → claude-code (plan) → codex (execute)
+   - Structured envelopes at every hop; downstream critiques upstream before acting
+   - Codex runs assess_plan — dangerous commands rejected, not blindly run
+
+2. ROUTING MODES
+   private   Loopback only. Private guard required. For sensitive / air-gapped work.
+   cloud     Cloud API tokens. No local infra needed.
+   hybrid    Cloud first, falls back to local LLM when tokens are missing.
+
+3. LOCAL LLM SUPPORT
+   - Each role points to its own llama.cpp server endpoint
+   - Built-in spec decoding config (n-gram / draft-model) → generates llama-server commands
+   - Probe: constrained-grammar check verifies each endpoint before pipeline starts
+
+4. SIDECAR VALIDATION
+   - Schema check on every hop — agent whitelist, message-type whitelist, payload fields
+   - Blocked commands: rm -rf /, shutdown, mkfs, fork bomb
+   - Private mode: loopback-only on all URLs including callbacks
+
+5. JSONL AUDIT LOG
+   - One JSON line per action — timestamp, session_id, kind
+   - Filter by session, query last N entries
+   - Session resume: rebuild plan from log, skip completed steps
+
+6. CLI + HTTP
+   CLI          opencac run, opencac audit, opencac resume, interactive REPL
+   HTTP         POST /run, GET /tasks/<id>, per-agent endpoints, /.well-known/agent.json
+   Distributed  CLI routes through HTTP service, sync and async
+
+7. SMART QUESTION ROUTING
+   - Ends with ? or starts with who/what/how/why → QA path, skips pipeline
+   - Task input → full pipeline, outputs artifacts
+   - Mentions docs/code/error/test → research step first
+```
+
+## Quick Start
+
+```bash
+git clone https://github.com/lpoee/opencac.git && cd opencac
+python3 -m venv .venv && . .venv/bin/activate && pip install .
+```
+
+```bash
+# Private (local llama.cpp shards)
+export A2A_ANTIGRAVITY_URL=http://127.0.0.1:18101
+export A2A_CLAUDE_CODE_URL=http://127.0.0.1:18102
+export A2A_CODEX_URL=http://127.0.0.1:18103
+opencac run "task" --mode private
+
+# Cloud
+export A2A_ANTIGRAVITY_TOKEN=...
+export A2A_CLAUDE_CODE_TOKEN=...
+export A2A_CODEX_TOKEN=...
+opencac run "task" --mode cloud
+
+# Hybrid
+export A2A_CLOUD_FALLBACK_LOCAL=1
+opencac run "task" --mode cloud
+```
+
+## Agent Integration
+
+Connect real AI agents for production-quality research, planning, and code generation.
+When set, the pipeline calls real agents first and falls back to local heuristics on failure.
+
+```bash
+# Antigravity — Gemini research via JSON-RPC (A2A protocol)
+export OPENCAC_RESEARCH_URL=http://127.0.0.1:18791
+
+# Claude Code — planning via Claude Bridge (Anthropic messages API)
+export OPENCAC_PLANNER_URL=http://127.0.0.1:9300
+
+# Codex — AI code generation via CLI
+export OPENCAC_CODEX_BINARY=/usr/local/bin/codex
+
+opencac run "refactor the auth module" --mode private
+```
+
+| Variable               | Agent         | Protocol                    | Purpose                    |
+| ---------------------- | ------------- | --------------------------- | -------------------------- |
+| `OPENCAC_RESEARCH_URL` | Antigravity   | JSON-RPC 2.0 `message/send` | Web research via Gemini    |
+| `OPENCAC_PLANNER_URL`  | Claude Bridge | `POST /v1/messages`         | Plan generation via Claude |
+| `OPENCAC_CODEX_BINARY` | Codex CLI     | JSONL subprocess            | AI code generation         |
+
+The `generate` plan action dispatches work to Codex CLI for AI-assisted code generation.
+Without these variables, the pipeline uses deterministic local heuristics (file search, template plans, subprocess execution).
+
+Docker:
+
+```bash
+docker build -t opencac .
+docker run --rm -p 8000:8000 -v "$(pwd)/data:/data" opencac
+```
+
+## Speculative Decoding
+
+```bash
+opencac run "task" --mode private \
+  --spec-type ngram-simple \
+  --draft-max 64 --draft-min 16
+```
+
+| Strategy                   | Description                          | VRAM        |
+| -------------------------- | ------------------------------------ | ----------- |
+| Self-speculative (default) | n-gram cache on main model           | Zero extra  |
+| Draft-model                | Smaller model generates draft tokens | Extra model |
+
+## HTTP API
+
+| Method | Path                             | Description       |
+| ------ | -------------------------------- | ----------------- |
+| `GET`  | `/.well-known/agent.json`        | Agent card        |
+| `GET`  | `/tasks/<id>`                    | Status + steps    |
+| `GET`  | `/audit?session_id=<id>&last=20` | Audit log         |
+| `POST` | `/run`                           | Run task          |
+| `POST` | `/run?distributed=1&async=1`     | Async distributed |
+| `POST` | `/agents/<agent>/message/send`   | Message an agent  |
+
+## Output
+
+- `artifacts/<session-id>/plan.json` — execution plan
+- `artifacts/<session-id>/result.md` — routing, strategy, step results
+- `.opencac/audit.jsonl` — full event log
+
+## Testing
+
+```bash
+PYTHONPATH=src pytest -q   # 32 tests
+```
+
+## Security
+
+See [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

opencac-0.2.0/README.md

@@ -0,0 +1,166 @@
+# OpenCAC
+
+**OpenCAC is multi-agent orchestration CLI for AI coding tools. Wires Claude Code, Antigravity, and Codex into one pipeline with validated handoffs, audit logging, and speculative decoding for local LLMs.**
+
+```bash
+pip install .
+opencac run "refactor the auth module" --mode private
+```
+
+## Why
+
+For developers who already use multiple AI coding agents and want one CLI to orchestrate them — with cloud models, local LLMs, or both.
+
+```
+   - Claude Code, Codex, Antigravity powerful alone, but each runs in its own world
+   - Cloud api burns money — every hosted model call costs real tokens.
+   - Local LLMs lack quality — small models are cheap but can't reliably produce production-grade code.
+
+OpenCAC solves this by chaining agents into a four-role pipeline where each agent does what it's best at, with structured validation at every hop.
+```
+
+## Features
+
+```
+1. FOUR-ROLE PIPELINE
+   dispatcher → antigravity (research) → claude-code (plan) → codex (execute)
+   - Structured envelopes at every hop; downstream critiques upstream before acting
+   - Codex runs assess_plan — dangerous commands rejected, not blindly run
+
+2. ROUTING MODES
+   private   Loopback only. Private guard required. For sensitive / air-gapped work.
+   cloud     Cloud API tokens. No local infra needed.
+   hybrid    Cloud first, falls back to local LLM when tokens are missing.
+
+3. LOCAL LLM SUPPORT
+   - Each role points to its own llama.cpp server endpoint
+   - Built-in spec decoding config (n-gram / draft-model) → generates llama-server commands
+   - Probe: constrained-grammar check verifies each endpoint before pipeline starts
+
+4. SIDECAR VALIDATION
+   - Schema check on every hop — agent whitelist, message-type whitelist, payload fields
+   - Blocked commands: rm -rf /, shutdown, mkfs, fork bomb
+   - Private mode: loopback-only on all URLs including callbacks
+
+5. JSONL AUDIT LOG
+   - One JSON line per action — timestamp, session_id, kind
+   - Filter by session, query last N entries
+   - Session resume: rebuild plan from log, skip completed steps
+
+6. CLI + HTTP
+   CLI          opencac run, opencac audit, opencac resume, interactive REPL
+   HTTP         POST /run, GET /tasks/<id>, per-agent endpoints, /.well-known/agent.json
+   Distributed  CLI routes through HTTP service, sync and async
+
+7. SMART QUESTION ROUTING
+   - Ends with ? or starts with who/what/how/why → QA path, skips pipeline
+   - Task input → full pipeline, outputs artifacts
+   - Mentions docs/code/error/test → research step first
+```
+
+## Quick Start
+
+```bash
+git clone https://github.com/lpoee/opencac.git && cd opencac
+python3 -m venv .venv && . .venv/bin/activate && pip install .
+```
+
+```bash
+# Private (local llama.cpp shards)
+export A2A_ANTIGRAVITY_URL=http://127.0.0.1:18101
+export A2A_CLAUDE_CODE_URL=http://127.0.0.1:18102
+export A2A_CODEX_URL=http://127.0.0.1:18103
+opencac run "task" --mode private
+
+# Cloud
+export A2A_ANTIGRAVITY_TOKEN=...
+export A2A_CLAUDE_CODE_TOKEN=...
+export A2A_CODEX_TOKEN=...
+opencac run "task" --mode cloud
+
+# Hybrid
+export A2A_CLOUD_FALLBACK_LOCAL=1
+opencac run "task" --mode cloud
+```
+
+## Agent Integration
+
+Connect real AI agents for production-quality research, planning, and code generation.
+When set, the pipeline calls real agents first and falls back to local heuristics on failure.
+
+```bash
+# Antigravity — Gemini research via JSON-RPC (A2A protocol)
+export OPENCAC_RESEARCH_URL=http://127.0.0.1:18791
+
+# Claude Code — planning via Claude Bridge (Anthropic messages API)
+export OPENCAC_PLANNER_URL=http://127.0.0.1:9300
+
+# Codex — AI code generation via CLI
+export OPENCAC_CODEX_BINARY=/usr/local/bin/codex
+
+opencac run "refactor the auth module" --mode private
+```
+
+| Variable               | Agent         | Protocol                    | Purpose                    |
+| ---------------------- | ------------- | --------------------------- | -------------------------- |
+| `OPENCAC_RESEARCH_URL` | Antigravity   | JSON-RPC 2.0 `message/send` | Web research via Gemini    |
+| `OPENCAC_PLANNER_URL`  | Claude Bridge | `POST /v1/messages`         | Plan generation via Claude |
+| `OPENCAC_CODEX_BINARY` | Codex CLI     | JSONL subprocess            | AI code generation         |
+
+The `generate` plan action dispatches work to Codex CLI for AI-assisted code generation.
+Without these variables, the pipeline uses deterministic local heuristics (file search, template plans, subprocess execution).
+
+Docker:
+
+```bash
+docker build -t opencac .
+docker run --rm -p 8000:8000 -v "$(pwd)/data:/data" opencac
+```
+
+## Speculative Decoding
+
+```bash
+opencac run "task" --mode private \
+  --spec-type ngram-simple \
+  --draft-max 64 --draft-min 16
+```
+
+| Strategy                   | Description                          | VRAM        |
+| -------------------------- | ------------------------------------ | ----------- |
+| Self-speculative (default) | n-gram cache on main model           | Zero extra  |
+| Draft-model                | Smaller model generates draft tokens | Extra model |
+
+## HTTP API
+
+| Method | Path                             | Description       |
+| ------ | -------------------------------- | ----------------- |
+| `GET`  | `/.well-known/agent.json`        | Agent card        |
+| `GET`  | `/tasks/<id>`                    | Status + steps    |
+| `GET`  | `/audit?session_id=<id>&last=20` | Audit log         |
+| `POST` | `/run`                           | Run task          |
+| `POST` | `/run?distributed=1&async=1`     | Async distributed |
+| `POST` | `/agents/<agent>/message/send`   | Message an agent  |
+
+## Output
+
+- `artifacts/<session-id>/plan.json` — execution plan
+- `artifacts/<session-id>/result.md` — routing, strategy, step results
+- `.opencac/audit.jsonl` — full event log
+
+## Testing
+
+```bash
+PYTHONPATH=src pytest -q   # 32 tests
+```
+
+## Security
+
+See [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

opencac-0.2.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opencac"
+version = "0.2.0"
+description = "OpenCAC: Claude Code, Antigravity, and Codex working together across cloud APIs and local models."
+requires-python = ">=3.9"
+authors = [{ name = "Codex" }]
+readme = "README.md"
+license = "MIT"
+keywords = [
+    "opencac",
+    "claude-code",
+    "codex",
+    "antigravity",
+    "multi-agent-orchestration",
+    "ai-coding-agent-pipeline",
+    "claude-code-codex-together",
+    "ai-coding-workflow-automation",
+    "orchestrate-ai-coding-tools",
+    "developer-cli-tools",
+    "ai-agent-chaining",
+    "reduce-ai-api-cost",
+    "local-llm-code-quality",
+    "air-gapped-ai-coding",
+    "private-ai-code-generation",
+    "local-llm",
+    "hybrid-ai",
+    "jsonl",
+    "audit-log",
+    "speculative-decoding",
+    "llama-cpp",
+    "validated-handoff",
+    "session-resume",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.scripts]
+opencac = "opencac.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/lpoee/opencac"
+Repository = "https://github.com/lpoee/opencac"
+Issues = "https://github.com/lpoee/opencac/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

opencac-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opencac-0.2.0/src/opencac/__init__.py

@@ -0,0 +1,12 @@
+__all__ = [
+    "agents",
+    "audit",
+    "cli",
+    "cli_runtime",
+    "pipeline",
+    "roles",
+    "runtime",
+    "schemas",
+    "service",
+    "sidecar",
+]

opencac-0.2.0/src/opencac/agents.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from .pipeline import resume_pipeline, run_pipeline
+from .roles import Antigravity, ClaudeCodePlanner, CodexExecutor
+from .runtime import InferenceConfig, RoutingConfig, Sidecar, ensure_private_runtime, make_envelope
+
+__all__ = [
+    "Antigravity",
+    "ClaudeCodePlanner",
+    "CodexExecutor",
+    "InferenceConfig",
+    "RoutingConfig",
+    "Sidecar",
+    "ensure_private_runtime",
+    "make_envelope",
+    "run_pipeline",
+    "resume_pipeline",
+]

opencac-0.2.0/src/opencac/audit.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class AuditLog:
+    path: Path
+
+    def __post_init__(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._io_lock = threading.Lock()
+        self._session_offsets: Dict[str, List[int]] = {}
+        self._all_offsets: List[int] = []
+        self._indexed_size = 0
+
+    def append(self, event: Dict[str, Any]) -> Dict[str, Any]:
+        enriched = {"ts": utc_now(), **event}
+        encoded = (json.dumps(enriched, ensure_ascii=False) + "\n").encode("utf-8")
+        with self._io_lock:
+            offset = self.path.stat().st_size if self.path.exists() else 0
+            with self.path.open("ab") as handle:
+                handle.write(encoded)
+            self._all_offsets.append(offset)
+            session_id = enriched.get("session_id")
+            if isinstance(session_id, str):
+                self._session_offsets.setdefault(session_id, []).append(offset)
+            self._indexed_size = offset + len(encoded)
+        return enriched
+
+    def read(self, session_id: Optional[str] = None, last: int = 20) -> List[Dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        with self._io_lock:
+            self._ensure_index_locked()
+            if session_id is None:
+                offsets = self._all_offsets[-last:]
+            else:
+                offsets = self._session_offsets.get(session_id, [])[-last:]
+            return self._read_offsets_locked(offsets)
+
+    def _ensure_index_locked(self) -> None:
+        if not self.path.exists():
+            self._session_offsets = {}
+            self._all_offsets = []
+            self._indexed_size = 0
+            return
+        current_size = self.path.stat().st_size
+        if current_size < self._indexed_size:
+            self._session_offsets = {}
+            self._all_offsets = []
+            self._indexed_size = 0
+        if current_size == self._indexed_size:
+            return
+        with self.path.open("rb") as handle:
+            handle.seek(self._indexed_size)
+            while True:
+                offset = handle.tell()
+                line = handle.readline()
+                if not line:
+                    break
+                try:
+                    item = json.loads(line.decode("utf-8"))
+                except json.JSONDecodeError:
+                    continue
+                self._all_offsets.append(offset)
+                session_id = item.get("session_id")
+                if isinstance(session_id, str):
+                    self._session_offsets.setdefault(session_id, []).append(offset)
+            self._indexed_size = handle.tell()
+
+    def _read_offsets_locked(self, offsets: List[int]) -> List[Dict[str, Any]]:
+        entries: List[Dict[str, Any]] = []
+        with self.path.open("rb") as handle:
+            for offset in offsets:
+                handle.seek(offset)
+                line = handle.readline()
+                if not line:
+                    continue
+                entries.append(json.loads(line.decode("utf-8")))
+        return entries