forgex-cli 0.1.0__tar.gz

forgex_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+        env:
+          CI: "1"  # docker/API-key tests self-skip; git tests use identity fallbacks
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src

forgex_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release with assets
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing (OIDC)
+    continue-on-error: true
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+        continue-on-error: true

forgex_cli-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.env
+.forgex/
+.DS_Store

forgex_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-10-06
+
+### Added
+- Multi-agent AI software engineering system (Architect, Builder, Expert Coder, Supervisor).
+- Permission-gated tool execution layer.
+- SQLite durable state and JSONL event store.
+- Git checkpointing with reversible rollback.
+- Self-healing repair loop with deterministic quality gates.
+- Context intelligence (AST indexing, import dependency graph, chunking, retrieval).
+- Multi-model ensemble review.
+- Docker sandbox execution isolation.
+- Typer CLI with full suite of commands.

forgex_cli-0.1.0/LICENSE

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

forgex_cli-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: forgex-cli
+Version: 0.1.0
+Summary: FORGEX — multi-agent AI software engineering. Plan. Build. Refine. Verify.
+Project-URL: Homepage, https://github.com/B-max12/Forgex
+Project-URL: Repository, https://github.com/B-max12/Forgex
+Project-URL: Issues, https://github.com/B-max12/Forgex/issues
+Project-URL: Changelog, https://github.com/B-max12/Forgex/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/B-max12/Forgex/tree/main/docs
+Author: FORGEX Contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,automation,cli,groq,llm,openai,software-engineering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.12
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FORGEX
+
+**Plan. Build. Refine. Verify.**
+
+FORGEX is a CLI-first autonomous AI software engineering system. Specialized
+agents — **Architect**, **Builder**, **Expert Coder**, **Supervisor** —
+collaborate on a real repository through permission-gated tools, Git
+checkpoints, a deterministic verification harness, and a bounded self-healing
+repair loop.
+
+> FORGEX is not a chatbot and not a code generator: it is an AI software
+> engineering *runtime* — with the safety rails that implies.
+
+```
+request → Architect → research → plan → [ Builder → Expert Coder →
+tests → Supervisor → PASS? done : repair ↺ ] (bounded by max_iterations)
+```
+
+**Status: v0.1.0 alpha** — the full pipeline works end-to-end with any
+OpenAI-compatible provider (Groq, OpenAI, local servers). Multi-model
+ensemble review, Docker sandboxing, and a context-intelligence layer are
+built in.
+
+## Installation
+
+### One-Line Install (Zero Environment Activation)
+
+```bash
+curl -sSL https://raw.githubusercontent.com/B-max12/Forgex/main/install.sh | bash
+```
+*(Or clone and run `./install.sh`)*
+
+### Via `pipx` or `uv tool`
+
+```bash
+pipx install forgex-cli          # once published to PyPI
+# or directly from GitHub:
+pipx install "git+https://github.com/B-max12/Forgex.git"
+```
+
+### From source (Developers):
+
+```bash
+git clone https://github.com/B-max12/Forgex.git && cd Forgex
+pip install -e ".[dev]"
+```
+
+Python 3.12+. Optional: Git (checkpoints — strongly recommended),
+Docker (sandboxing), ripgrep (faster search).
+
+## Quickstart
+
+### The Universal Way (Zero Learning Curve)
+
+Simply run `forgex` and describe what you want in plain English:
+
+```bash
+forgex
+```
+
+```text
+forgex ❯ Build me a FastAPI Todo API with SQLite and pytest
+```
+
+FORGEX handles the complete lifecycle automatically:
+1. **Auto-initializes** the project workspace and git repository if needed
+2. **Plans** architecture and task breakdown (Architect agent)
+3. **Implements** code and tests across tasks (Builder + Expert Coder)
+4. **Verifies** deterministically (tests, lint, typecheck)
+5. **Self-heals** and auto-repairs if any verification gates fail
+6. **Snapshots** a clean, reversible Git checkpoint on success!
+
+Follow up naturally with conversational context:
+```text
+forgex ❯ now add rate limiting to those endpoints
+forgex ❯ fix the failing tests in users.py
+```
+
+### One-Shot CLI / CI/CD Mode
+
+Run tasks directly from your shell without opening the REPL:
+
+```bash
+forgex "Create a FastAPI Todo API with SQLite and pytest"
+# Or:
+forgex do "Add JWT authentication with refresh tokens"
+```
+
+### Granular Power User Commands
+
+For granular manual control, individual pipeline stages remain available:
+
+```bash
+forgex plan "Add caching layer"     # run architect planning only
+forgex build                         # execute existing plan tasks
+forgex verify                        # run tests and lint deterministically
+forgex fix                           # verify + repair loop without replanning
+forgex checkpoint "Stable release"   # snapshot Git state
+forgex rollback                      # undo to previous checkpoint
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `forgex init [DIR]` | initialize a project (state, events, SQLite index) |
+| `forgex plan [REQUEST] [--dry-run]` | Architect: analysis → registry research → implementation plan |
+| `forgex build [REQUEST] [--file F] [--resume] [--dry-run]` | full pipeline with the repair loop |
+| `forgex fix` | verify + supervise + repair until green — no rebuild |
+| `forgex run [-- CMD]` | run the project's start command (policy-gated) |
+| `forgex task list / run ID` | inspect / execute single tasks (Builder + review) |
+| `forgex review [TASK] [--base C]` | Expert Coder review — single model or ensemble |
+| `forgex verify` | deterministic tests/build/lint — no LLM |
+| `forgex supervise` | verification + LLM audit + quality gates → verdict |
+| `forgex status / logs / diff` | project state, event stream, git diff |
+| `forgex checkpoint / rollback` | Git checkpoints; reversible rollback |
+| `forgex models [catalog\|health]` | bindings, capability catalog, live provider ping |
+| `forgex context stats\|search` | context index and relevance retrieval |
+| `forgex tools list\|run` | inspect / manually run agent tools |
+| `forgex config show\|get\|set\|setup` | layered configuration |
+| `forgex doctor [--ping]` | environment and provider health |
+
+Every command supports `--json` and `--plain` (CI/SSH friendly).
+
+## Providers
+
+| Type | Target | Notes |
+|---|---|---|
+| `groq` | Groq API | default binding: llama-3.3-70b-versatile |
+| `openai_compatible` | OpenAI & any compatible endpoint | set base_url |
+| `local` | Ollama, llama.cpp, vLLM, LM Studio | base_url required, keyless |
+
+Provider-independent by design: per-agent model bindings, capability-aware
+routing, retry with backoff, fallback chains, and multi-model ensemble
+review (`[ensemble] enabled = true` — e.g. Groq + OpenAI reviewing the same
+diff in parallel, findings corroborated before fixes are applied).
+
+## Security
+
+- Agents act only through permission-gated tools; every path is workspace-confined; `.forgex/`, `.git/` and secret files are untouchable.
+- Commands are argv-only (no shells), policy-filtered (deny list, optional allowlist, network approval), and — with `[sandbox] enabled = true` — run in hardened Docker containers (no network by default, host FS invisible).
+- Secrets never enter prompts: env-only storage, sanitized child environments, pattern-based content scrubbing.
+- Deterministic quality gates: no model verdict can pass a red test suite or an incomplete build.
+
+Full model + residual risks: `docs/security.md`.
+
+## License
+
+MIT

forgex_cli-0.1.0/README.md

@@ -0,0 +1,149 @@
+# FORGEX
+
+**Plan. Build. Refine. Verify.**
+
+FORGEX is a CLI-first autonomous AI software engineering system. Specialized
+agents — **Architect**, **Builder**, **Expert Coder**, **Supervisor** —
+collaborate on a real repository through permission-gated tools, Git
+checkpoints, a deterministic verification harness, and a bounded self-healing
+repair loop.
+
+> FORGEX is not a chatbot and not a code generator: it is an AI software
+> engineering *runtime* — with the safety rails that implies.
+
+```
+request → Architect → research → plan → [ Builder → Expert Coder →
+tests → Supervisor → PASS? done : repair ↺ ] (bounded by max_iterations)
+```
+
+**Status: v0.1.0 alpha** — the full pipeline works end-to-end with any
+OpenAI-compatible provider (Groq, OpenAI, local servers). Multi-model
+ensemble review, Docker sandboxing, and a context-intelligence layer are
+built in.
+
+## Installation
+
+### One-Line Install (Zero Environment Activation)
+
+```bash
+curl -sSL https://raw.githubusercontent.com/B-max12/Forgex/main/install.sh | bash
+```
+*(Or clone and run `./install.sh`)*
+
+### Via `pipx` or `uv tool`
+
+```bash
+pipx install forgex-cli          # once published to PyPI
+# or directly from GitHub:
+pipx install "git+https://github.com/B-max12/Forgex.git"
+```
+
+### From source (Developers):
+
+```bash
+git clone https://github.com/B-max12/Forgex.git && cd Forgex
+pip install -e ".[dev]"
+```
+
+Python 3.12+. Optional: Git (checkpoints — strongly recommended),
+Docker (sandboxing), ripgrep (faster search).
+
+## Quickstart
+
+### The Universal Way (Zero Learning Curve)
+
+Simply run `forgex` and describe what you want in plain English:
+
+```bash
+forgex
+```
+
+```text
+forgex ❯ Build me a FastAPI Todo API with SQLite and pytest
+```
+
+FORGEX handles the complete lifecycle automatically:
+1. **Auto-initializes** the project workspace and git repository if needed
+2. **Plans** architecture and task breakdown (Architect agent)
+3. **Implements** code and tests across tasks (Builder + Expert Coder)
+4. **Verifies** deterministically (tests, lint, typecheck)
+5. **Self-heals** and auto-repairs if any verification gates fail
+6. **Snapshots** a clean, reversible Git checkpoint on success!
+
+Follow up naturally with conversational context:
+```text
+forgex ❯ now add rate limiting to those endpoints
+forgex ❯ fix the failing tests in users.py
+```
+
+### One-Shot CLI / CI/CD Mode
+
+Run tasks directly from your shell without opening the REPL:
+
+```bash
+forgex "Create a FastAPI Todo API with SQLite and pytest"
+# Or:
+forgex do "Add JWT authentication with refresh tokens"
+```
+
+### Granular Power User Commands
+
+For granular manual control, individual pipeline stages remain available:
+
+```bash
+forgex plan "Add caching layer"     # run architect planning only
+forgex build                         # execute existing plan tasks
+forgex verify                        # run tests and lint deterministically
+forgex fix                           # verify + repair loop without replanning
+forgex checkpoint "Stable release"   # snapshot Git state
+forgex rollback                      # undo to previous checkpoint
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `forgex init [DIR]` | initialize a project (state, events, SQLite index) |
+| `forgex plan [REQUEST] [--dry-run]` | Architect: analysis → registry research → implementation plan |
+| `forgex build [REQUEST] [--file F] [--resume] [--dry-run]` | full pipeline with the repair loop |
+| `forgex fix` | verify + supervise + repair until green — no rebuild |
+| `forgex run [-- CMD]` | run the project's start command (policy-gated) |
+| `forgex task list / run ID` | inspect / execute single tasks (Builder + review) |
+| `forgex review [TASK] [--base C]` | Expert Coder review — single model or ensemble |
+| `forgex verify` | deterministic tests/build/lint — no LLM |
+| `forgex supervise` | verification + LLM audit + quality gates → verdict |
+| `forgex status / logs / diff` | project state, event stream, git diff |
+| `forgex checkpoint / rollback` | Git checkpoints; reversible rollback |
+| `forgex models [catalog\|health]` | bindings, capability catalog, live provider ping |
+| `forgex context stats\|search` | context index and relevance retrieval |
+| `forgex tools list\|run` | inspect / manually run agent tools |
+| `forgex config show\|get\|set\|setup` | layered configuration |
+| `forgex doctor [--ping]` | environment and provider health |
+
+Every command supports `--json` and `--plain` (CI/SSH friendly).
+
+## Providers
+
+| Type | Target | Notes |
+|---|---|---|
+| `groq` | Groq API | default binding: llama-3.3-70b-versatile |
+| `openai_compatible` | OpenAI & any compatible endpoint | set base_url |
+| `local` | Ollama, llama.cpp, vLLM, LM Studio | base_url required, keyless |
+
+Provider-independent by design: per-agent model bindings, capability-aware
+routing, retry with backoff, fallback chains, and multi-model ensemble
+review (`[ensemble] enabled = true` — e.g. Groq + OpenAI reviewing the same
+diff in parallel, findings corroborated before fixes are applied).
+
+## Security
+
+- Agents act only through permission-gated tools; every path is workspace-confined; `.forgex/`, `.git/` and secret files are untouchable.
+- Commands are argv-only (no shells), policy-filtered (deny list, optional allowlist, network approval), and — with `[sandbox] enabled = true` — run in hardened Docker containers (no network by default, host FS invisible).
+- Secrets never enter prompts: env-only storage, sanitized child environments, pattern-based content scrubbing.
+- Deterministic quality gates: no model verdict can pass a red test suite or an incomplete build.
+
+Full model + residual risks: `docs/security.md`.
+
+## License
+
+MIT

forgex_cli-0.1.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in FORGEX, please email security@forgex.dev or open a private security advisory on GitHub.
+
+See [docs/security.md](docs/security.md) for the complete security architecture, mitigations, and known residual limitations.

forgex_cli-0.1.0/docs/agents.md

@@ -0,0 +1,19 @@
+# Agents
+
+All agents share one machinery: versioned prompts (`prompts/*.md`, `name:vN`), the structured-output loop (schema-in-prompt → parse → bounded repair), and — for acting agents — the **tool loop**: multi-turn native tool calling, or a strict JSON protocol for models without tool support. The loop itself has zero privileges; every call goes through the per-agent permission set at the `ToolExecutor`.
+
+| Agent | Prompt | Permissions | Output |
+|---|---|---|---|
+| Architect | `architect:v1` | read, research | `AnalysisResult` → `ArchitecturePlan` |
+| Builder | `builder:v1` | read, write, delete, terminal, git, test, build | `BuilderResult` |
+| Expert Coder | `expert_coder:v1` | read, write, delete, terminal, git, test, build | `ExpertCoderResult` |
+| Reviewer | `reviewer:v1` | read, git, test | `ReviewFindings` |
+| Supervisor | `supervisor:v1` | read, test, build, git | `SupervisorJudgment` → `SupervisorReport` |
+
+## Collaboration Protocol
+
+1. **Architect** analyzes repository and decomposes goals into dependency-ordered tasks (`TASK-001`, `TASK-002`, ...).
+2. **Builder** implements tasks one at a time within pre-task checkpoints.
+3. **Expert Coder** inspects diffs and refines changes (or ensemble reviewers corroborated by judge).
+4. **Supervisor** audits deterministic test/build results against acceptance criteria and issues verdicts.
+5. In case of failure, a `REPAIR-NNN` task is generated for targeted self-healing.

forgex_cli-0.1.0/docs/architecture.md

@@ -0,0 +1,33 @@
+# Architecture
+
+## Layers
+
+```
+CLI (Typer/Rich)      thin commands — services hold the logic (future server reuses them)
+Orchestration         workflow engine · state · events · checkpoints · run lock
+Agents                architect · builder · expert coder · reviewer · supervisor
+Model layer           provider adapters · router (bindings, fallback, ensemble) · registry
+Tools (permission-    filesystem · search · terminal · git · tests · dependencies
+gated, the ONLY        context: index · dependency graph · retrieval · chunking
+I/O path for agents)
+Storage               SQLite (queryable metadata) + JSON state in .forgex/ (truth)
+                      + git (checkpoints) — filesystem stays the source of truth
+```
+
+## State Machine
+
+`INITIALIZING → ANALYZING → RESEARCHING → PLANNING → BUILDING ⇄ REVIEWING → TESTING → SUPERVISING → (COMPLETED | REPAIRING → TESTING …)` with `FAILED` and `CANCELLED` reachable from any active state. Transitions are explicit (`forgex/orchestration/workflow.py`); the engine walks them, saves state at each step, and `--resume` re-enters idempotently.
+
+## Invariants
+
+1. Agents have zero direct I/O — only tools, only within their permission set.
+2. Every mutation is checkpointed first; every rollback is reversible.
+3. Verification is deterministic; LLM judgment can only worsen a verdict.
+4. JSON files in `.forgex/` are the durable truth; SQLite is a rebuildable index.
+5. Every significant action emits an event (`forgex logs`).
+6. One active run per project (run lock); interrupts never corrupt state.
+7. Bounded loops everywhere: repair iterations, tool rounds, transcript chars.
+
+## Data Flow
+
+`events.jsonl` (append-only, fsync) ↔ SQLite mirrors (events, runs, tasks, model_usage, checkpoints, errors) · `state.json`/`tasks.json` (atomic writes) · git commits as checkpoints · `cache/context-index.json` (mtime-invalidated).

forgex_cli-0.1.0/docs/configuration.md

@@ -0,0 +1,56 @@
+# Configuration
+
+FORGEX features layered configuration (highest wins):
+CLI args → environment → project `.forgex/config.toml` → global `~/.forgex/config.toml` → schema defaults.
+
+Secrets are NEVER saved in configuration files. Only the name of the environment variable (e.g. `api_key_env = "FORGEX_GROQ_API_KEY"`) is stored. Real secrets live in the environment or `~/.forgex/.env` (permissions `0600`).
+
+## Sections
+
+### `[workflow]`
+- `max_iterations = 5`: Maximum repair loops before stopping.
+
+### `[permissions]`
+- `mode = "ask"`: Policy mode (`"auto"`, `"ask"`, or `"safe"`).
+
+### `[terminal]`
+- `allowed = []`: Allowlist of commands (if non-empty, only these may run).
+- `denied = []`: Additional denied commands.
+- `timeout_seconds = 120`: Default timeout for command execution.
+- `max_output_bytes = 1000000`: Output size cap before truncation.
+
+### `[sandbox]`
+- `enabled = false`: Whether to run commands in Docker containers.
+- `network = false`: Whether sandboxed containers have network access.
+- `image = "python:3.12-slim"`: Docker image to execute in.
+- `cpu_limit = "2.0"`: CPU limit.
+- `memory_limit = "1g"`: Memory limit.
+- `read_only = true`: Read-only container rootfs with tmpfs `/tmp`.
+
+### `[models]`
+Configure model bindings per agent role:
+```toml
+[models.architect]
+provider = "groq"
+model = "llama-3.3-70b-versatile"
+
+[models.builder]
+provider = "groq"
+model = "llama-3.3-70b-versatile"
+
+[models.expert_coder]
+provider = "groq"
+model = "llama-3.3-70b-versatile"
+
+[models.supervisor]
+provider = "groq"
+model = "llama-3.3-70b-versatile"
+```
+
+### `[fallback]`
+- `enabled = true`: Whether to attempt fallback providers if primary fails.
+- `providers = ["openai_compatible"]`: Ordered fallback providers.
+
+### `[ensemble]`
+- `enabled = false`: Multi-model ensemble review.
+- `reviewers = 2`: Number of parallel reviewer models.

forgex_cli-0.1.0/docs/decisions.md

@@ -0,0 +1,26 @@
+# Architecture Decision Records
+
+The consolidated decision log (§44).
+
+| ADR | Decision | Reason | Consequence |
+|---|---|---|---|
+| 001 | MIT, src-layout, hatchling | Simple packaging, clean namespace | Dynamic version from `__init__.py` |
+| 002 | JSON files = durable truth; SQLite = rebuildable index | Git-friendly, human-inspectable state | Dual writes centralized in `ProjectStores` |
+| 003 | Atomic writes + fsync'd events | Interrupts never corrupt state (§36) | Durability priority |
+| 004 | Forward-only SQLite migrations | Phase-safe schema upgrades | New tables require new numbered migration |
+| 005 | Secrets: env-only, `api_key_env` indirection, `.env` loading | Secrets never in config, git, or prompts (§46) | Setup writes `~/.forgex/.env` `0600` |
+| 006 | Argv-only execution; all shells denied | Shell injection structurally impossible (§45) | No pipes or `&&` in command tool |
+| 007 | Sanitized child env allowlist | Child processes cannot leak parent env vars | Explicit env passing when needed |
+| 008 | Per-agent permission matrix, fail-closed | Least privilege (§32) | Unknown roles get empty permissions |
+| 009 | Deterministic verification; quality gates | Models cannot talk past red tests (§56/58) | Supervisor read-only by permission |
+| 010 | Ensemble reviewers read-only; explicit bindings | Parallel writers clobber; diversity must be real | Single senior applier resolves findings |
+| 011 | Corroboration judge is deterministic code | Auditable, cheap, testable | Jaccard lexical clustering of findings |
+| 012 | Tool loop: native tools or JSON protocol fallback | Works with any OpenAI-compatible model (§31) | Fallback enables local/small model support |
+| 013 | Structured output: schema in prompt + bounded repair | Robust structured extraction without forced schema API | Max 2 attempts then controlled error |
+| 014 | Pre-mutation checkpoints; reversible rollback | All repository modifications reversible (§21) | Safety checkpoint before hard reset |
+| 015 | Context: AST index + import graph + lexical scoring | Low token footprint without heavy vector DB | Fast, deterministic file ranking |
+| 016 | Pattern redaction at every content on-ramp | Prevents credentials entering model context | Over-redaction preferred to leakage |
+| 017 | Transcript budgets (soft warning + hard stop) | Prevents infinite loops blowing context limits | Checkpoint-recoverable stop |
+| 018 | Run lock (`run.lock`) with PID liveness check | Prevents concurrent runs corrupting state | Advisory lock per project |
+| 019 | Research = official registries only, fixed endpoints | Zero SSRF / prompt injection surface (§8) | No arbitrary web crawling |
+| 020 | Degradation is logged, never silent | Observability and operator trust | Warnings emitted when falling back |

forgex_cli-0.1.0/docs/providers.md

@@ -0,0 +1,47 @@
+# Providers
+
+FORGEX is provider-independent (spec section 2.2). Agents talk to the `ModelRouter`; the router resolves your configuration into provider adapters. No agent code contains provider-specific logic.
+
+## Built-in Adapters
+
+| Type | Target | Notes |
+|---|---|---|
+| `groq` | Groq API | OpenAI-compatible; default `base_url` + `FORGEX_GROQ_API_KEY` |
+| `openai_compatible` | OpenAI & any compatible endpoint | requires `base_url` |
+| `local` | Ollama, llama.cpp, vLLM, LM Studio | requires `base_url`; no auth by default |
+
+## Configuration Example
+
+```toml
+[providers.groq]
+type = "groq"
+default_model = "llama-3.3-70b-versatile"
+api_key_env = "FORGEX_GROQ_API_KEY"
+
+[providers.ollama]
+type = "local"
+base_url = "http://localhost:11434/v1"
+default_model = "llama3.1:8b"
+
+[models.architect]
+provider = "groq"
+model = "llama-3.3-70b-versatile"
+```
+
+Resolution per agent: `models.<agent>.model` → provider's `default_model` → configuration error. Nothing is guessed.
+
+## Secrets
+
+- Config files store only the name of the environment variable.
+- Keys are read from the environment or `~/.forgex/.env`.
+- `forgex config setup` writes keys to `~/.forgex/.env` (`chmod 0600`).
+- Provider error text is scrubbed through a redactor before surfacing.
+
+## Fallback
+
+```toml
+[fallback]
+enabled = true
+providers = ["openai_compatible"]
+```
+After a provider exhausts retries (rate limits, 5xx, timeouts), the router tries the next fallback provider using its `default_model`.