opencode-arch 1.0.0__tar.gz

opencode_arch-1.0.0/.architecture-model.yaml

@@ -0,0 +1,444 @@
+meta:
+  project: opencode-arch
+  system: OpenCode Architecture Extension
+  schema_version: '1.4'
+  generated_at: '2026-07-08'
+  source_language: python
+
+entities:
+  actors:
+    - id: ACT-DEV
+      name: Developer
+      status: ACTIVE
+      type: human
+      goals:
+        - Extract architecture from repositories
+        - Generate SE documentation
+        - Validate code against models
+    - id: ACT-AGENT
+      name: LLM Agent
+      status: ACTIVE
+      type: system
+      goals:
+        - Consume compressed context via MCP tools
+        - Produce architecture models
+        - Regenerate code from models
+    - id: ACT-OPENCODE
+      name: OpenCode Runner
+      status: ACTIVE
+      type: external-service
+      goals:
+        - Execute LLM prompts as subprocess
+
+  capabilities:
+    - id: CAP-EXTRACT
+      name: Architecture Extraction
+      status: ACTIVE
+      f_block: F1
+      priority: high
+      requirements:
+        - Scan repository AST
+        - Produce validated architecture model
+        - Achieve score >= 80/100
+    - id: CAP-GENERATE
+      name: Code Generation
+      status: ACTIVE
+      f_block: F1
+      priority: high
+      requirements:
+        - Regenerate code from model
+        - Run tests to validate
+        - Iterate until pass rate met
+    - id: CAP-DOCS
+      name: SE Document Generation
+      status: ACTIVE
+      f_block: F1
+      priority: high
+      requirements:
+        - Select artifacts based on model richness
+        - Assemble context from model and manifest
+        - Generate grounded documentation
+    - id: CAP-REGEN
+      name: Subsystem Regen-Loop
+      status: ACTIVE
+      f_block: F1
+      priority: high
+      requirements:
+        - Decompose system into subsystems
+        - Iterate per-subsystem until convergence
+        - Support blind mode (model-only context)
+    - id: CAP-LEARN
+      name: Learning Loop
+      status: ACTIVE
+      f_block: F3
+      priority: medium
+      requirements:
+        - Classify failure patterns
+        - Adapt prompts based on patterns
+        - Generate report cards
+        - Extract and store lessons
+    - id: CAP-MCP
+      name: MCP Tool Serving
+      status: ACTIVE
+      f_block: F4
+      priority: high
+      requirements:
+        - Expose scan/slice/validate/extract tools
+        - Compress context within token budget
+        - Serve via stdio MCP protocol
+    - id: CAP-TELEMETRY
+      name: Telemetry & Metrics
+      status: ACTIVE
+      f_block: F7
+      priority: medium
+      requirements:
+        - Record tool invocations
+        - Track regen outcomes
+        - Store learning curve data
+
+  behaviors:
+    - id: BEH-EXTRACT
+      name: Extract Architecture
+      status: ACTIVE
+      trigger: CLI command 'opencode-arch extract'
+      actor: ACT-DEV
+      steps:
+        - Scan repository to generate manifest
+        - Format context from manifest within token budget
+        - Send extraction prompt to runner
+        - Parse YAML response into model
+        - Validate model (target score >= 80)
+        - Store model to .architecture-model.yaml
+      pattern: sequential
+    - id: BEH-REGEN
+      name: Regen-Loop Iteration
+      status: ACTIVE
+      trigger: CLI command 'opencode-arch regen-loop'
+      actor: ACT-DEV
+      steps:
+        - Load model and decompose into subsystems
+        - For each subsystem build prompt with model context
+        - Send prompt to runner (blind or normal mode)
+        - Run subsystem tests
+        - If failing, analyze gaps and build feedback
+        - Iterate until convergence or max iterations
+        - Run full test suite
+        - Generate report card
+      pattern: pipeline
+    - id: BEH-DOCS
+      name: Generate Documentation
+      status: ACTIVE
+      trigger: CLI command 'opencode-arch docs generate'
+      actor: ACT-DEV
+      steps:
+        - Load architecture model
+        - Generate reality manifest
+        - Select artifacts based on model richness
+        - For each artifact assemble context
+        - Send generation prompt to runner
+        - Write result with frontmatter
+        - Generate index.md
+        - Run validation
+      pattern: sequential
+    - id: BEH-MCP-SCAN
+      name: MCP Scan Tool
+      status: ACTIVE
+      trigger: Agent calls architect_scan
+      actor: ACT-AGENT
+      steps:
+        - Receive repo_path from agent
+        - Call generate_manifest on target
+        - Return manifest dict to agent
+      pattern: sequential
+
+  interfaces:
+    - id: IF-CLI
+      name: CLI Interface
+      status: ACTIVE
+      type: internal
+      protocol: argparse
+      provider: COMP-CLI
+      consumer: ACT-DEV
+      endpoints:
+        - {method: extract, path: 'opencode-arch extract <repo>'}
+        - {method: generate, path: 'opencode-arch generate <repo>'}
+        - {method: regen-loop, path: 'opencode-arch regen-loop --repo <path>'}
+        - {method: docs, path: 'opencode-arch docs {generate,list,validate}'}
+        - {method: metrics, path: 'opencode-arch metrics'}
+        - {method: report, path: 'opencode-arch report'}
+    - id: IF-MCP
+      name: MCP Tool Protocol
+      status: ACTIVE
+      type: external
+      protocol: MCP stdio
+      provider: COMP-MCP
+      consumer: ACT-AGENT
+      endpoints:
+        - {method: architect_scan, path: tools/scan}
+        - {method: architect_slice, path: tools/slice}
+        - {method: architect_validate, path: tools/validate}
+        - {method: architect_extract, path: tools/extract}
+        - {method: architect_generate, path: tools/generate}
+    - id: IF-RUNNER
+      name: Runner Backend Protocol
+      status: ACTIVE
+      type: internal
+      protocol: subprocess
+      provider: COMP-RUNNER
+      consumer: COMP-CLI
+      endpoints:
+        - {method: run, path: 'opencode run <prompt> --dir <path>'}
+    - id: IF-TELEMETRY
+      name: Telemetry Store Interface
+      status: ACTIVE
+      type: internal
+      protocol: SQLite
+      provider: COMP-TELEMETRY
+      consumer: COMP-CLI
+      endpoints:
+        - {method: record, path: store.record()}
+        - {method: query, path: store.query()}
+        - {method: log_regen_outcome, path: store.log_regen_outcome()}
+    - id: IF-ARCH-MODEL
+      name: Architecture Model API
+      status: ACTIVE
+      type: internal
+      protocol: Python import
+      provider: ACT-OPENCODE
+      consumer: COMP-CLI
+      endpoints:
+        - {method: load_model, path: architecture_model.load_model()}
+        - {method: generate_manifest, path: architecture_model.generate_manifest()}
+        - {method: select_artifacts, path: architecture_model.select_artifacts()}
+        - {method: validate_model, path: architecture_model.validate_model()}
+
+  constraints:
+    - id: CON-TOKENS
+      name: Token Budget Constraint
+      status: ACTIVE
+      type: performance
+      metric: context_tokens
+      threshold: '4000 tokens default, configurable'
+      rationale: LLM context windows are limited; compression enables larger repos
+    - id: CON-NO-HALLUCINATION
+      name: No Hallucination Constraint
+      status: ACTIVE
+      type: reliability
+      metric: grounding_accuracy
+      threshold: '100% — all claims must trace to model/manifest'
+      rationale: Core value proposition is grounded documentation
+    - id: CON-TIMEOUT
+      name: Runner Timeout
+      status: ACTIVE
+      type: performance
+      metric: execution_time
+      threshold: '600 seconds per LLM call'
+      rationale: Prevent hung subprocesses from blocking pipeline
+    - id: CON-PERMISSIONS
+      name: Cross-Directory Access
+      status: ACTIVE
+      type: security
+      metric: filesystem_access
+      threshold: 'Requires --dangerously-skip-permissions flag'
+      rationale: opencode run needs access to target repos outside CWD
+
+  layers:
+    - id: LAYER-CLI
+      name: CLI Layer
+      status: ACTIVE
+      order: 1
+      technology: [argparse, asyncio]
+      directories: [src/opencode_arch/cli]
+    - id: LAYER-MCP
+      name: MCP Server Layer
+      status: ACTIVE
+      order: 1
+      technology: [FastMCP, mcp-protocol]
+      directories: [src/opencode_arch/mcp]
+    - id: LAYER-LEARNING
+      name: Learning Layer
+      status: ACTIVE
+      order: 2
+      technology: [dataclasses, regex]
+      directories: [src/opencode_arch/learning]
+    - id: LAYER-RUNNER
+      name: Runner Layer
+      status: ACTIVE
+      order: 3
+      technology: [subprocess, Protocol]
+      directories: [src/opencode_arch/runner]
+    - id: LAYER-TELEMETRY
+      name: Telemetry Layer
+      status: ACTIVE
+      order: 3
+      technology: [SQLite]
+      directories: [src/opencode_arch/telemetry]
+
+  components:
+    - id: COMP-CLI
+      name: CLI Commands
+      status: ACTIVE
+      layer: LAYER-CLI
+      f_block: F1
+      technology: argparse
+      kind: module
+      files:
+        - src/opencode_arch/cli/main.py
+        - src/opencode_arch/cli/extract.py
+        - src/opencode_arch/cli/generate.py
+        - src/opencode_arch/cli/bench.py
+        - src/opencode_arch/cli/regen_loop.py
+        - src/opencode_arch/cli/docs.py
+        - src/opencode_arch/cli/docs_validator.py
+        - src/opencode_arch/cli/metrics.py
+        - src/opencode_arch/cli/gap_analyzer.py
+      responsibilities:
+        - Parse CLI arguments
+        - Orchestrate extraction, generation, regen-loop, docs workflows
+        - Display results to user
+    - id: COMP-MCP
+      name: MCP Server
+      status: ACTIVE
+      layer: LAYER-MCP
+      f_block: F4
+      technology: FastMCP
+      kind: service
+      files:
+        - src/opencode_arch/mcp/__main__.py
+        - src/opencode_arch/mcp/server.py
+        - src/opencode_arch/mcp/tools/scan.py
+        - src/opencode_arch/mcp/tools/slice.py
+        - src/opencode_arch/mcp/tools/validate.py
+        - src/opencode_arch/mcp/tools/extract.py
+        - src/opencode_arch/mcp/tools/generate.py
+      responsibilities:
+        - Expose architecture tools via MCP protocol
+        - Compress context within token budget
+        - Bridge between LLM agent and architecture-model-standard
+    - id: COMP-RUNNER
+      name: OpenCode Runner
+      status: ACTIVE
+      layer: LAYER-RUNNER
+      f_block: F6
+      technology: subprocess
+      kind: library
+      files:
+        - src/opencode_arch/runner/base.py
+        - src/opencode_arch/runner/opencode.py
+      responsibilities:
+        - Invoke opencode run as subprocess
+        - Handle timeouts and errors
+        - Return structured RunResult
+    - id: COMP-LEARNING
+      name: Learning Loop
+      status: ACTIVE
+      layer: LAYER-LEARNING
+      f_block: F3
+      technology: dataclasses
+      kind: module
+      files:
+        - src/opencode_arch/learning/classifier.py
+        - src/opencode_arch/learning/adapter.py
+        - src/opencode_arch/learning/assessor.py
+        - src/opencode_arch/learning/lessons.py
+        - src/opencode_arch/learning/maintainer.py
+        - src/opencode_arch/learning/patterns.py
+      responsibilities:
+        - Classify test failure patterns
+        - Adapt prompts based on patterns
+        - Generate report cards with grades
+        - Extract and store lessons
+        - Detect documentation drift
+    - id: COMP-TELEMETRY
+      name: Telemetry Store
+      status: ACTIVE
+      layer: LAYER-TELEMETRY
+      f_block: F7
+      technology: SQLite
+      kind: data-store
+      files:
+        - src/opencode_arch/telemetry/store.py
+        - src/opencode_arch/telemetry/recorder.py
+      responsibilities:
+        - Persist tool invocation metrics
+        - Store regen outcomes and learning data
+        - Provide query interface for metrics display
+    - id: COMP-PROMPTS
+      name: Prompt Templates
+      status: ACTIVE
+      layer: LAYER-CLI
+      f_block: F5
+      technology: Python strings
+      kind: library
+      files:
+        - src/opencode_arch/prompts/regen.py
+        - src/opencode_arch/prompts/extract.py
+      responsibilities:
+        - Define LLM prompt templates
+        - Structure system/user prompts for extraction and regen
+
+relationships:
+  - from: COMP-CLI
+    to: COMP-RUNNER
+    type: depends-on
+    description: CLI uses runner to invoke LLM
+  - from: COMP-CLI
+    to: COMP-TELEMETRY
+    type: depends-on
+    description: CLI records metrics after operations
+  - from: COMP-CLI
+    to: COMP-LEARNING
+    type: depends-on
+    description: Regen-loop uses learning for adaptation
+  - from: COMP-CLI
+    to: COMP-PROMPTS
+    type: depends-on
+    description: CLI uses prompt templates
+  - from: COMP-MCP
+    to: IF-ARCH-MODEL
+    type: consumes
+    description: MCP tools call architecture-model-standard APIs
+  - from: COMP-LEARNING
+    to: COMP-TELEMETRY
+    type: depends-on
+    description: Learning stores lessons and patterns
+  - from: COMP-CLI
+    to: CAP-EXTRACT
+    type: realizes
+    description: extract command realizes extraction capability
+  - from: COMP-CLI
+    to: CAP-GENERATE
+    type: realizes
+    description: generate command realizes generation capability
+  - from: COMP-CLI
+    to: CAP-DOCS
+    type: realizes
+    description: docs command realizes documentation capability
+  - from: COMP-CLI
+    to: CAP-REGEN
+    type: realizes
+    description: regen-loop realizes subsystem regeneration
+  - from: COMP-MCP
+    to: CAP-MCP
+    type: realizes
+    description: MCP server realizes tool serving
+  - from: COMP-LEARNING
+    to: CAP-LEARN
+    type: realizes
+    description: Learning module realizes learning loop
+  - from: COMP-TELEMETRY
+    to: CAP-TELEMETRY
+    type: realizes
+    description: Telemetry store realizes metrics tracking
+  - from: CON-TOKENS
+    to: COMP-MCP
+    type: constrained-by
+    description: MCP tools must respect token budget
+  - from: CON-NO-HALLUCINATION
+    to: COMP-CLI
+    type: constrained-by
+    description: Docs generator must only use grounded data
+  - from: CON-TIMEOUT
+    to: COMP-RUNNER
+    type: constrained-by
+    description: Runner enforces timeout on subprocess

opencode_arch-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

opencode_arch-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Tests
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev,mcp]"
+      - run: pytest tests/ -v --tb=short -m "not e2e" --ignore=tests/test_extract_from_code.py --ignore=tests/test_docs_cli.py

opencode_arch-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.egg
+.venv/

opencode_arch-1.0.0/.opencode/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+package.json
+package-lock.json
+bun.lock
+.gitignore

opencode_arch-1.0.0/.opencode/metrics/benchmark-2026-07-31.json

@@ -0,0 +1,198 @@
+{
+  "date": "2026-07-31",
+  "version": "0.5.0",
+  "features": [
+    "SourceGraph protocol (language-agnostic)",
+    "ComponentInterface (provides/requires)",
+    "Compression ratio guard (50x/200x thresholds)",
+    "Minimum contract guarantee",
+    "Block manifest consumption",
+    "Complexity-proportional budget allocation"
+  ],
+  "repos": [
+    {
+      "name": "flask",
+      "language": "python",
+      "modules": 6,
+      "import_edges": 8,
+      "components": 6,
+      "interfaces": 16,
+      "avg_confidence": 0.808,
+      "contracts": 6,
+      "patterns": 4,
+      "source_kb": 575,
+      "compression_ratio_16k": 9.2
+    },
+    {
+      "name": "celery",
+      "language": "python",
+      "modules": 161,
+      "import_edges": 550,
+      "components": 23,
+      "interfaces": 140,
+      "avg_confidence": 0.86,
+      "contracts": 23,
+      "patterns": 17,
+      "source_kb": 3470,
+      "compression_ratio_16k": 55.5
+    },
+    {
+      "name": "django",
+      "language": "python",
+      "modules": 905,
+      "import_edges": 3083,
+      "components": 219,
+      "interfaces": 1200,
+      "avg_confidence": 0.656,
+      "contracts": 219,
+      "patterns": 55,
+      "source_kb": 19039,
+      "compression_ratio_16k": 304.6
+    },
+    {
+      "name": "sqlalchemy",
+      "language": "python",
+      "modules": 73,
+      "import_edges": 18,
+      "components": 33,
+      "interfaces": 0,
+      "avg_confidence": 0.583,
+      "contracts": 33,
+      "patterns": 3,
+      "source_kb": 19987,
+      "compression_ratio_16k": 319.8
+    },
+    {
+      "name": "pydantic",
+      "language": "python",
+      "modules": 69,
+      "import_edges": 229,
+      "components": 40,
+      "interfaces": 244,
+      "avg_confidence": 0.712,
+      "contracts": 40,
+      "patterns": 16,
+      "source_kb": 7101,
+      "compression_ratio_16k": 113.6
+    },
+    {
+      "name": "fastapi",
+      "language": "python",
+      "modules": 25,
+      "import_edges": 30,
+      "components": 9,
+      "interfaces": 10,
+      "avg_confidence": 0.639,
+      "contracts": 9,
+      "patterns": 2,
+      "source_kb": 3898,
+      "compression_ratio_16k": 62.4
+    },
+    {
+      "name": "httpx",
+      "language": "python",
+      "modules": 6,
+      "import_edges": 10,
+      "components": 5,
+      "interfaces": 8,
+      "avg_confidence": 0.85,
+      "contracts": 5,
+      "patterns": 5,
+      "source_kb": 556,
+      "compression_ratio_16k": 8.9
+    },
+    {
+      "name": "requests",
+      "language": "python",
+      "modules": 19,
+      "import_edges": 65,
+      "components": 9,
+      "interfaces": 36,
+      "avg_confidence": 0.672,
+      "contracts": 9,
+      "patterns": 2,
+      "source_kb": 397,
+      "compression_ratio_16k": 6.4
+    },
+    {
+      "name": "invoke",
+      "language": "python",
+      "modules": 31,
+      "import_edges": 56,
+      "components": 4,
+      "interfaces": 4,
+      "avg_confidence": 0.7,
+      "contracts": 4,
+      "patterns": 1,
+      "source_kb": 699,
+      "compression_ratio_16k": 11.2
+    },
+    {
+      "name": "rich",
+      "language": "python",
+      "modules": 23,
+      "import_edges": 1,
+      "components": 1,
+      "interfaces": 0,
+      "avg_confidence": 0.5,
+      "contracts": 1,
+      "patterns": 0,
+      "source_kb": 1704,
+      "compression_ratio_16k": 27.3
+    },
+    {
+      "name": "express",
+      "language": "javascript",
+      "modules": 50,
+      "import_edges": 22,
+      "components": 15,
+      "interfaces": 0,
+      "avg_confidence": 0.3,
+      "contracts": 15,
+      "patterns": 0,
+      "source_kb": 535,
+      "compression_ratio_16k": 8.6
+    },
+    {
+      "name": "gin",
+      "language": "go",
+      "modules": 58,
+      "import_edges": 10,
+      "components": 14,
+      "interfaces": 14,
+      "avg_confidence": 0.332,
+      "contracts": 14,
+      "patterns": 0,
+      "source_kb": 674,
+      "compression_ratio_16k": 10.8
+    },
+    {
+      "name": "axum",
+      "language": "rust",
+      "modules": 239,
+      "import_edges": 0,
+      "components": 24,
+      "interfaces": 0,
+      "avg_confidence": 0.3,
+      "contracts": 24,
+      "patterns": 0,
+      "source_kb": 1312,
+      "compression_ratio_16k": 21.0
+    }
+  ],
+  "summary": {
+    "total_repos": 13,
+    "languages": [
+      "go",
+      "javascript",
+      "python",
+      "rust"
+    ],
+    "total_components": 402,
+    "total_interfaces": 1672,
+    "weighted_avg_confidence": 0.626,
+    "zero_contract_components": 0,
+    "total_modules": 1665,
+    "total_import_edges": 4082
+  }
+}