ananke-plexus 0.3.0__tar.gz → 0.3.2__tar.gz

{ananke_plexus-0.3.0 → ananke_plexus-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ananke-plexus
-Version: 0.3.0
+Version: 0.3.2
 Summary: A local-first ADLC control plane for governed agentic software engineering.
 Project-URL: Homepage, https://github.com/Neo-Pragnya/Ananke-Plexus
 Project-URL: Documentation, https://neo-pragnya.github.io/Ananke-Plexus/
@@ -55,6 +55,7 @@ Requires-Dist: pytest>=8; extra == 'all'
 Requires-Dist: watchfiles>=0.21; extra == 'all'
 Requires-Dist: zstandard>=0.22; extra == 'all'
 Provides-Extra: dev
+Requires-Dist: hatchling>=1.26; extra == 'dev'
 Requires-Dist: mypy>=1.15; extra == 'dev'
 Requires-Dist: pre-commit>=4; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
@@ -770,6 +771,8 @@ ananke doctor [--json]          # environment diagnostics
 ananke verify                   # full local gate suite
 ananke config show              # show effective config
 ananke config migrate [--apply] # migrate config schema
+ananke docs build | serve       # offline docs site (bundled — no PyPI/GitHub needed)
+ananke workflow install-pack setup && ananke workflow run setup  # bundle commands, run together
 ```
 
 ### `ananke spec` — specification lifecycle

{ananke_plexus-0.3.0 → ananke_plexus-0.3.2}/README.md

@@ -623,6 +623,8 @@ ananke doctor [--json]          # environment diagnostics
 ananke verify                   # full local gate suite
 ananke config show              # show effective config
 ananke config migrate [--apply] # migrate config schema
+ananke docs build | serve       # offline docs site (bundled — no PyPI/GitHub needed)
+ananke workflow install-pack setup && ananke workflow run setup  # bundle commands, run together
 ```
 
 ### `ananke spec` — specification lifecycle

ananke_plexus-0.3.2/docs/concepts/architecture.md

@@ -0,0 +1,172 @@
+# System Architecture
+
+## Overview
+
+Ananke Plexus follows a **core + ports + adapters** hexagonal architecture. The stable center contains Ananke's governance semantics. External tooling remains fully replaceable.
+
+```mermaid
+flowchart TB
+    subgraph Entry["👤 Entrypoints"]
+        CLI["⌨️ ananke CLI"]
+        APMCLI["📦 apm CLI"]
+        HOOKS["🪝 Git Hooks"]
+        MCP["🔌 MCP Clients"]
+        CI["⚙️ CI/CD"]
+    end
+
+    subgraph Core["⚖️ Ananke Core"]
+        CONFIG["⚙️ Config"]
+        POLICY["🛡️ Policy Engine"]
+        EXEC["🤖 Execution Director"]
+        EVENTS["📡 Event Bus"]
+        TELEMETRY["📊 Telemetry"]
+        PERM["🔐 Permissions"]
+        STATE["🔁 Run State Machine"]
+    end
+
+    subgraph Domain["🧠 Domain Subsystems"]
+        SPEC["📜 Spec / BMAD"]
+        CALM["🏗️ CALM Architecture"]
+        GRAPH["🕸️ Graph Intelligence"]
+        APM["📦 APM"]
+        REGISTRY["🗂️ Skill & Agent Registry"]
+        GATES["🧪 Verification Gates"]
+        EVIDENCE["🧾 Evidence"]
+    end
+
+    subgraph Adapters["🔌 Adapters"]
+        JIRA["Jira"] 
+        SCM["GitHub / Bitbucket"]
+        GRAPHIFY["Graphifyy"]
+        CRG["Code Review Graph"]
+        COPILOT["Copilot"] 
+        Q["Amazon Q"]
+        KIRO["Kiro"]
+        HERMES["Hermes"]
+    end
+
+    Entry --> Core
+    Core --> Domain
+    Domain --> Adapters
+    Adapters -. Results .-> Domain
+```
+
+---
+
+## Package layout
+
+```
+ananke-plexus/
+└── src/ananke/plexus/
+    ├── cli/            — Typer CLI entrypoints (ananke + apm)
+    ├── core/           — IDs, result types, path helpers, workflow audit
+    ├── config/         — Config models, loader, migration, secrets resolver
+    ├── contracts/      — BMAD compiler: behavior, model, architecture
+    ├── specs/          — Spec models, service, providers, lock, drift
+    ├── architecture/   — CALM loader, validation, delta, Mermaid rendering
+    ├── graph/          — Canonical graph models, providers (native/Graphifyy/CRG)
+    ├── policy/         — Policy engine, rule schema, builtin packs
+    ├── gates/          — Gate runner, adapters (ruff, mypy, pytest, semgrep...)
+    ├── execution/      — Plan DAG, scheduler, checkpoint, approvals, compensation
+    ├── backends/       — AgentBackend protocol, Copilot/Q/Kiro/Hermes/fake adapters
+    ├── lifecycle/      — Git service, worktrees, Jira, Bitbucket, PR evidence
+    ├── hooks/          — Git hook manager, stages, runner
+    ├── mcp/            — MCP server, tools, resources, prompts, auth
+    ├── apm/            — Skill manifests, registry, installer, sandbox, lockfile
+    ├── evidence/       — Evidence bundle, SARIF 2.1.0, hash, retention (+ registry capability snapshot)
+    ├── registry/       — Skill & Agent Registry: SQLite + content-addressed store, importers,
+    │                     resolver, ananke.lock, activation, docs generator, HTTP server
+    ├── evals/          — Enterprise evaluation harness: traces, evaluators, judges, regression
+    ├── testing/        — Unified test & quality harness: adapters, profiles, quality gate
+    ├── events/         — In-process event bus with JSONL audit log
+    ├── telemetry/      — OpenTelemetry adapter, noop
+    └── plugins/        — Entry-point discovery, plugin metadata
+```
+
+---
+
+## Design principles
+
+### Local-first
+
+Code, specs, graph state, verification, and evidence can remain entirely local. No hosted service is required.
+
+### Ports and adapters
+
+Every external integration is isolated behind a protocol/interface:
+
+```python
+GraphProvider  →  NativeGraphProvider | GraphifyyAdapter | CodeReviewGraphAdapter
+AgentBackend   →  CopilotBackend | AmazonQBackend | KiroBackend | HermesBackend | FakeBackend
+SCMPort        →  BitbucketAdapter | GitHubAdapter
+IssuePort      →  JiraAdapter
+ScannerPort    →  RuffAdapter | SemgrepAdapter | GitleaksAdapter | TrivyAdapter
+```
+
+### Immutable, content-addressed capabilities
+
+Skills and agents live in the [registry](registry.md): every version is an immutable, hash-verified payload; mutable state (trust, channel, lifecycle) is separate and audited. Resolution is deterministic, policy-aware and explainable, and produces a reproducible `ananke.lock`.
+
+### Fail closed for hard gates
+
+When a configured hard gate cannot execute, the default result is **BLOCKED**, not "pass."
+
+Soft gates return: `PASS | WARN | SKIPPED | UNAVAILABLE`  
+Hard gates return: `PASS | BLOCKED | ERROR`
+
+### Evidence before mutation
+
+Every mutating step records:
+
+1. Requested intent
+2. Policy decision
+3. Preconditions
+4. Execution result
+5. Verification result
+6. Artifact hashes
+7. Audit record
+
+### Capability discovery
+
+Every backend declares a `BackendCapabilities` model. The orchestrator asks the registry for capabilities and constructs a compatible execution plan.
+
+---
+
+## Configuration precedence
+
+Highest wins:
+
+1. CLI flags (`--project`, `--offline`, `--json`)
+2. Process environment variables
+3. `.ananke/config.local.toml`
+4. `.ananke/config.toml`
+5. User config
+6. Built-in defaults
+
+---
+
+## Event system
+
+Every subsystem emits typed domain events to an in-process event bus. Events are appended to `.ananke/evidence/*.jsonl` for audit trails.
+
+Registry events (`artifact.registered`, `artifact.promoted`, `artifact.yanked`, `artifact.quarantined`, …) are also written to an append-only `registry_events` table.
+
+Key events: `RequirementCaptured`, `SpecCreated`, `SpecLocked`, `GateCompleted`, `BackendInvoked`, `PullRequestCreated`, `EvidenceFinalized`, `ApprovalRequested`, `ApprovalGranted`
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | generic failure |
+| 2 | invalid usage/config |
+| 3 | policy blocked |
+| 4 | verification failed |
+| 5 | dependency/tool unavailable |
+| 6 | integration failure |
+| 7 | authentication/authorization |
+| 8 | spec drift |
+| 9 | architecture violation |
+| 10 | cancelled |

ananke_plexus-0.3.2/docs/concepts/bmad.md

@@ -0,0 +1,196 @@
+# Ananke BMAD — Behavior, Model, Architecture
+
+Within Ananke Plexus, **BMAD** means:
+
+> **Behavior — Model — Architecture Driven Development**
+
+These represent three distinct forms of engineering truth that must all align for a change to be considered proven.
+
+```mermaid
+flowchart TB
+    SPEC["📜 Specification"]
+    B["🧪 Behavior<br/>What must happen?"]
+    M["🧱 Model<br/>What structures exist?"]
+    A["🏗️ Architecture<br/>How may they interact?"]
+    IMPL["💻 Implementation"]
+
+    SPEC --> B
+    SPEC --> M
+    SPEC --> A
+
+    B --> IMPL
+    M --> IMPL
+    A --> IMPL
+
+    IMPL -->|"Tests"| B
+    IMPL -->|"Schema Validation"| M
+    IMPL -->|"Graph Reconciliation"| A
+```
+
+---
+
+## Compiling BMAD from a requirement
+
+```bash
+# Create a requirement with acceptance criteria
+ananke spec create \
+  --id PROJ-101 \
+  --title "Add idempotent payment webhook" \
+  --acceptance "Duplicate events are deduplicated" \
+  --acceptance "Idempotency key is stored per transaction"
+
+# Compile all BMAD artifacts
+ananke bmad compile --feature-dir .ananke/specs/PROJ-101
+```
+
+This produces:
+
+```
+.ananke/specs/PROJ-101/
+├── bmad.yaml                    — BMAD index
+├── model-contract.yaml          — API schema skeleton
+├── architecture-contract.yaml   — CALM + allow/deny rules
+└── tests/
+    ├── test_proj_101_behavior.py    — Failing pytest skeleton
+    └── proj_101.feature             — Gherkin scenarios
+```
+
+---
+
+## Behavior contract
+
+Behavior is expressed through failing tests and Gherkin scenarios. Every generated test records its full traceability chain:
+
+```
+Requirement → Acceptance Criterion → Scenario → Test ID
+```
+
+Generated pytest skeleton (`tests/test_proj_101_behavior.py`):
+
+```python
+import pytest
+
+# Traceability: PROJ-101 -> AC-1 -> test_ac_1_duplicate_events_are_deduplicated
+@pytest.mark.requirement('PROJ-101')
+@pytest.mark.ac('1')
+def test_ac_1_duplicate_events_are_deduplicated() -> None:
+    """AC-1: Duplicate events are deduplicated"""
+    # TODO: implement acceptance criterion assertion
+    pytest.fail('not implemented')
+```
+
+Generated Gherkin feature:
+
+```gherkin
+Feature: Add idempotent payment webhook
+  # Requirement: PROJ-101
+
+  Scenario: AC-1 — Duplicate events are deduplicated
+    Given the system is in a known state
+    When the condition for AC-1 is met
+    Then the system satisfies the acceptance criterion
+```
+
+### Behavior principle
+
+Never claim that an automatically generated test proves the requirement unless traceability exists. Every test records `Requirement → AC → Scenario → Test ID`.
+
+---
+
+## Model contract
+
+Model contracts define API schemas, event payloads, domain value objects, and compatibility rules.
+
+Generated `model-contract.yaml`:
+
+```yaml
+contract_id: model-proj-101
+requirement_id: PROJ-101
+title: Add idempotent payment webhook
+schemas:
+  - name: proj-101_request
+    type: object
+    description: API request boundary for this requirement
+  - name: proj-101_response
+    type: object
+    description: API response boundary for this requirement
+compatibility_policy: backward_compatible
+boundary_types:
+  - api_request
+  - api_response
+```
+
+Example domain model:
+
+```python
+from pydantic import BaseModel
+from datetime import datetime
+from decimal import Decimal
+from uuid import UUID
+
+class PaymentWebhookPayload(BaseModel):
+    transaction_id: UUID
+    customer_id: UUID
+    amount: Decimal
+    currency: str
+    occurred_at: datetime
+    idempotency_key: str
+```
+
+---
+
+## Architecture contract
+
+Architecture contracts are checked against the CALM system document, graph provider facts, and component allow/deny rules.
+
+Generated `architecture-contract.yaml`:
+
+```yaml
+contract_id: arch-proj-101
+requirement_id: PROJ-101
+calm_ref: .ananke/architecture/system.calm.json
+allowed_dependencies: []
+denied_dependencies: []
+invariant_ids: []
+import_rules:
+  deny_cross_domain_imports: true
+  deny_circular_imports: true
+```
+
+---
+
+## Verifying BMAD artifacts
+
+```bash
+ananke bmad verify --feature-dir .ananke/specs/PROJ-101
+# exits 0 if all artifacts present, 4 if missing
+
+ananke bmad show --feature-dir .ananke/specs/PROJ-101
+# prints the bmad.yaml index
+
+ananke bmad trace --feature-dir .ananke/specs/PROJ-101
+# shows requirement → AC → test traceability
+```
+
+---
+
+## BMAD vs BMAD-METHOD
+
+Ananke uses **Ananke BMAD** (Behavior, Model, Architecture) as its internal contract triad.
+
+The external **BMAD-METHOD** ecosystem is separate. If supported, it lives under `ananke.plexus.integrations.bmad_method` to avoid semantic collision.
+
+---
+
+## Drift detection
+
+After locking the spec, Ananke detects when artifacts have changed:
+
+```bash
+ananke spec lock --feature-dir .ananke/specs/PROJ-101
+ananke spec diff --feature-dir .ananke/specs/PROJ-101
+# → [] if no drift
+# → ["HASH_MISMATCH:spec.md"] if spec changed after lock
+```
+
+Drift types: `REQUIREMENT_DRIFT`, `SPEC_DRIFT`, `ARCHITECTURE_DRIFT`, `MODEL_DRIFT`, `POLICY_DRIFT`, `TOOLCHAIN_DRIFT`, `GRAPH_DRIFT`

ananke_plexus-0.3.2/docs/concepts/evaluation.md

@@ -0,0 +1,147 @@
+# Enterprise Agent Evaluation Harness
+
+The Ananke Plexus evaluation harness is the **quality-intelligence plane** of the ADLC. It provides enterprise-grade, runtime-neutral agent quality assurance — without making any single evaluation library a hard dependency.
+
+## Design Philosophy
+
+### Deterministic-First
+Every native evaluator is deterministic: given identical inputs, it produces identical scores. Non-deterministic LLM judges are isolated behind the `JudgeGateway` and used only when no deterministic signal exists.
+
+### Trace-Only Rescoring
+Evaluations operate on `AgentTrace` — a canonical span model that normalises traces from Pydantic AI, Microsoft Agent Framework, Hermes, or any OTel-compliant system. You can **re-evaluate historical traces** without re-running the agent.
+
+### Enterprise Dependency Policy
+The core `ananke-plexus` package has zero evaluation-library dependencies. Every third-party adapter (`mlflow`, `deepeval`, `ragas`, etc.) is a **lazy import** activated only when the appropriate `[eval-*]` extra is installed:
+
+| Extra | Activates |
+|---|---|
+| `eval-otel` | OpenTelemetry trace export |
+| `eval-mlflow` | MLflow experiment tracking (preferred enterprise backend) |
+| `eval-deepeval` | DeepEval metrics |
+| `eval-inspect` | Inspect AI |
+| `eval-ragas` | Ragas RAG evaluators |
+| `eval-openevals` | OpenEvals |
+| `eval-agentevals` | AgentEvals trajectory matching |
+| `eval-enterprise` | OTel + MLflow + jsonschema bundle |
+
+## Canonical Trace Model
+
+```python
+from ananke.plexus.evals import AgentTrace, AgentSpan, SpanKind, Usage
+
+trace = AgentTrace(
+    trace_id="t-001",
+    run_id="run-001",
+    runtime="pydantic-ai",
+    spans=[
+        AgentSpan(
+            span_id="s-001",
+            kind=SpanKind.TOOL,
+            name="read_file",
+            start_time=...,
+            end_time=...,
+            attributes={"file": "spec.md"},
+        )
+    ],
+    usage=Usage(prompt_tokens=1200, completion_tokens=300, total_tokens=1500),
+)
+```
+
+`SpanKind` values: `agent | model | planning | tool | retrieval | subagent | approval | verification | policy | filesystem | shell`
+
+## Evaluation Domains
+
+Ananke ships 80+ native evaluators across 9 quality dimensions:
+
+| Domain | Example Evaluators |
+|---|---|
+| **Outcome** | ExactMatch, Regex, JsonEquality, SchemaConformance, TaskCompletion |
+| **Trajectory** | StrictTrajectory, LoopDetection, ForbiddenStep, StepEfficiency |
+| **Tool Use** | ToolSelection, ToolAllowlist, ToolDenylist, IdempotencyCheck |
+| **Planning** | PlanCoverage, PlanDependency, PlanFeasibility, PlanAdherence |
+| **Retrieval/RAG** | ContextPrecision, ContextRecall, Faithfulness, AnswerRelevance |
+| **Safety/Governance** | PermissionBoundary, SecretLeakage, ApprovalGate, ShellPolicy |
+| **Architecture** | SpecAdherence, BehaviorCoverage, ArchitectureConformance |
+| **Efficiency** | TokenBudget, CostBudget, Latency, RetryCount, CacheEfficiency |
+| **Resilience** | FailureRecognition, RecoveryPath, CheckpointUsage, Rollback |
+
+Plus multi-agent (`DelegationAccuracy`, `HandoffCompleteness`) and meta-evaluation (`cohens_kappa`, `judge_human_agreement`, `detect_positional_bias`).
+
+## Evaluation Status
+
+Each `EvalScore` carries an `EvalStatus`:
+
+| Status | Meaning |
+|---|---|
+| `pass` | Meets threshold |
+| `warn` | Marginal — review recommended |
+| `review` | Human judgement required |
+| `fail` | Below threshold |
+| `error` | Evaluator threw an exception |
+| `skipped` | Evaluator requires optional package not installed |
+
+## Gate Policy
+
+After evaluation, the policy engine converts `EvalScore[]` into an `EvalGateDecision`:
+
+| Verdict | Meaning |
+|---|---|
+| `PASS` | All hard requirements met |
+| `WARN` | Soft thresholds missed; proceed with caution |
+| `REVIEW` | Human approval required before merge |
+| `BLOCK` | Hard failure; pipeline blocked |
+
+Configure thresholds in `.ananke/evals/config.yaml`:
+
+```yaml
+suites:
+  standard:
+    hard_fail_on: [safety, outcome]
+    warn_on: [efficiency, resilience]
+    pass_threshold: 0.8
+    warn_threshold: 0.6
+```
+
+## LLM Judge Governance
+
+The `EnterpriseJudgeGateway` ensures:
+- Only approved providers are used (`azure | bedrock | anthropic | openai | local | custom`)
+- Secret patterns are redacted before any text is sent to a provider
+- Trusted rubrics are separated from untrusted agent output via `JudgeInputEnvelope.to_prompt()`
+- Credentials are resolved from the Ananke secrets resolver — never hardcoded
+
+## Baseline Regression
+
+Compare a candidate run against an approved baseline:
+
+```bash
+ananke eval baseline create --run my-run-id --id v1.0-baseline
+ananke eval compare --baseline v1.0-baseline --run my-new-run
+```
+
+Policy enforcement uses bootstrap confidence intervals to distinguish statistical noise from real regressions.
+
+## Evidence Bundle
+
+Every evaluation run writes a tamper-evident bundle:
+
+```
+.ananke/evidence/<run-id>/eval/
+  scores.json          # EvalScore[] with normalized values
+  policy-decision.json # EvalGateDecision
+  manifest.json        # SHA-256 checksums
+  reports/
+    report.md          # PR-ready Markdown table
+    summary.json       # Machine-readable JSON
+    junit.xml          # JUnit XML for CI integration
+```
+
+## ADLC Integration
+
+The evaluation harness is wired into the ADLC at the **Evaluation Gate**:
+
+```
+Spec → Plan → Implement → [Eval Gate] → Evidence → Deploy
+```
+
+When `gate_decision.blocks` is true, `ananke eval run` exits with code 1, blocking the pipeline. CI pipelines consume `junit.xml` for test result reporting.