sengol 0.8.0__tar.gz

sengol-0.8.0/.claude/skills/pr-review/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: pr-review
+description: Triage and resolve review comments on sengol/product PRs — gather (haiku) → decide FIX/REJECT/SKIP (opus) → implement (sonnet) → verify+ship (haiku). Use when a PR has review comments to work through. Args: one or more "<owner>/<repo>#<number>".
+---
+
+# PR Review Triage — four stages, model pinned per stage
+
+Cost rule: each stage runs on its named model. The expensive model (opus/fable) sees ONLY the
+gathered comment list — never raw diffs or whole files. Announce the model switch before each
+stage; if the harness can't switch models, say so and continue, keeping stage boundaries.
+
+## Stage 1 — GATHER (haiku). No judgments, no fixes, no file edits.
+
+For each PR argument, fetch via GitHub MCP tools (fall back to `gh` with `--jq` only if MCP
+is unavailable): review comment threads, review summaries, and issue comments.
+
+Output ONE numbered list, grouped by repo:
+```
+[N] repo · file:line · author · priority badge if present
+    verbatim body (strip bot boilerplate/badges)
+    type: question / requested-change / suggestion / nit / informational
+```
+End with counts by type. STOP — next stage decides.
+
+## Stage 2 — DECIDE (opus or fable). One verdict per item: FIX / REJECT / SKIP.
+
+Decide against the session brief (product `phases/phase-<N>/session-<Nx>.md`) and the repo
+invariants. Standing REJECT grounds:
+- **Out of scope** — expands into another session's territory (cite the brief).
+- **Invariant violation** — would weaken: binary `EvalScore.passed` (Rule 2); ControlBook
+  drives reports (Rule 4); ADR-0052 store boundary; append-only AuditStore + HMAC payload
+  scope; sinks/exporters never fail the gate or add latency; credentials from env only,
+  never `sengol.yaml`; `...` is valid in Protocol bodies (PEP 544).
+- **Vendor brokering** — Sengol never maps/holds vendor credentials.
+
+Standing SKIP: bot overview wrappers, duplicates, pure informational.
+
+Output a decision table (#, item, verdict, one-sentence action or reply), flag the 2–3
+riskiest FIXes, then STOP for the user's approval. **If zero FIXes: recommend merging and
+stop — do not run stages 3–4.**
+
+## Stage 3 — IMPLEMENT (sonnet). Only after explicit approval.
+
+- Trivial fixes first, then functional. Touch only files the comments implicate.
+- Post each approved REJECT reply verbatim on its thread (one comment per thread, never a
+  new thread). SKIPs stay silent.
+- Test rules: no full-suite runs while iterating; SSE/streaming tested via the async
+  generator with bounded reads + `aclose()` — never GET through TestClient; never "fix" a
+  hang by raising a timeout.
+- When all fixes are written: STOP. Stage 4 verifies.
+
+## Stage 4 — VERIFY + SHIP (haiku).
+
+1. Changed test files only, each bounded:
+   `uv run pytest <files> -q --timeout=30 -p no:cacheprovider` (never pipe through tail/head).
+2. Green → full fast suite ONCE (`-m "not llm and not integration"`) + `npx vitest run` ONCE
+   if frontend files changed.
+3. Push (the PR updates automatically), confirm CI green via MCP check-runs, report a
+   one-line status per PR. A code fix needed mid-verify goes back to Stage 3 — never fixed
+   on haiku. If still red after one full pass: STOP and report the failure output verbatim.

sengol-0.8.0/.cursorrules

@@ -0,0 +1,134 @@
+# Sengol v3.6 — Cursor Rules (Phases 1–2)
+
+## Identity
+Sengol — Apache 2.0 Python 3.12 SDK. AI governance for regulated financial institutions.
+Building Phases 1–2: SDK core + OSFI E-23 PDF compliance report.
+
+## Critical Rules — Never Violate
+
+### 1. PolicyId is open str — NEVER Literal
+```python
+# ✓ CORRECT — any org can define their own
+PolicyId = str   # "OSFI_E23", "MY_BANK_POLICY_V3", "MAS_TRM" all valid
+
+# ✗ WRONG — breaks for Singapore, Saudi, Indian banks
+PolicyId = Literal["OSFI_E23", "FINTRAC_6F"]
+```
+
+### 2. EvalScore.passed is binary bool — NEVER float
+```python
+# ✓ CORRECT
+EvalScore(passed=True, failure_mode=None)
+EvalScore(passed=False, failure_mode="REQUIRED_DISCLOSURE_MISSING")
+
+# ✗ WRONG
+EvalScore(score=0.87)  # NEVER — pre-commit blocks this
+```
+
+### 3. Deterministic before LLM — asyncio.gather() for LLM
+```python
+# EvalSuite runs in this order:
+# 1. All DeterministicEvaluator — sync, <1ms, no API
+# 2. Short-circuit if CRITICAL failure (skip LLM)
+# 3. All LLMEvaluator — asyncio.gather() — O(1) not O(n)
+```
+
+### 4. ControlBook drives reports — never bypass it
+```python
+# ✓ CORRECT — works for any regulation
+ComplianceReportGenerator(controlbook=controlbook).generate(agent_id, period)
+
+# ✗ WRONG — hardcoded, breaks for non-OSFI customers
+OSFIReportGenerator().generate(agent_id, period)
+```
+
+### 5. Audit records: sign before write, append-only
+```python
+# ✓ CORRECT
+signed = record.sign(signing_key)
+await audit_store.write(signed)
+
+# ✗ WRONG — audit_store has no update() method
+await audit_store.update(record_id, new_data)
+```
+
+## Code Patterns to Suggest
+
+### Deterministic evaluator skeleton
+```python
+from sengol.core.evaluator import DeterministicEvaluator
+from sengol.core.types import LLMEvalInput, EvalScore
+
+class RequiredDisclosureEvaluator(DeterministicEvaluator):
+    """Checks OSFI E-23 required disclosure phrases. Observed at: Canadian retail bank."""
+    name = "RequiredDisclosureEvaluator"
+    failure_mode = "REQUIRED_DISCLOSURE_MISSING"
+    policies: list[str] = ["OSFI_E23"]
+    version: str = "1.0.0"
+
+    def evaluate(self, input: LLMEvalInput) -> EvalScore:
+        passed = "not a guarantee" in input.response.lower()
+        return EvalScore(
+            evaluator=self.name,
+            passed=passed,
+            failure_mode=None if passed else self.failure_mode,
+            reason="Disclosure present" if passed else "Missing required disclosure",
+        )
+```
+
+### LLM evaluator stub (Phase 1)
+```python
+class FaithfulnessEvaluator(LLMEvaluator):
+    name = "FaithfulnessEvaluator"
+    failure_mode = "FAITHFULNESS_FAILURE"
+    policies: list[str] = ["OSFI_E23"]
+
+    async def evaluate_async(self, input: LLMEvalInput) -> EvalScore:
+        # Phase 1 stub — Phase 3 wires real LLM judge
+        return EvalScore(evaluator=self.name, passed=True, failure_mode=None)
+```
+
+### AuditRecord (sign before write)
+```python
+signed = record.sign(os.getenv("SENGOL_SIGNING_KEY"))
+await audit_store.write(signed)
+assert await audit_store.verify(signed.record_id)
+```
+
+### ControlBook-driven report
+```python
+report = ComplianceReportGenerator(
+    audit_store=audit_store,
+    controlbook=controlbook,
+).generate(
+    agent_id="rag-advisor-001",
+    period_from=datetime(2026, 1, 1),
+    period_to=datetime(2026, 5, 1),
+)
+# report.pdf_path — hand to CRO
+# report.json_path — machine-readable evidence
+```
+
+## Never Suggest
+- `PolicyId = Literal[...]` — must be `str`
+- `EvalScore(score=0.87)` — float primary output
+- `print()` — use `structlog`
+- `logging.basicConfig()` — use `structlog`
+- Sequential LLM evaluator calls — use `asyncio.gather()`
+- `UPDATE` or `DELETE` on `audit_records`
+- Hardcoded OSFI-only report generator
+- `import openai` — respect `ControlBook.judge_by_tier`
+
+## File Locations
+- New evaluator → `sengol/evaluators/{deterministic|llm}/{name}.py`
+- New type → `sengol/core/types.py` (check spec §5 first)
+- New API route → `sengol/api/routes/{name}.py`
+- New CLI command → `sengol/cli/main.py` (Typer)
+- Policy catalog → `sengol/policies/catalog.yaml`
+
+## Logging
+```python
+import structlog
+log = structlog.get_logger()
+log.info("eval.complete", evaluator="MyEval", passed=True, latency_ms=12)
+```

sengol-0.8.0/.dockerignore

@@ -0,0 +1,16 @@
+# Files excluded from the Docker build context.
+#
+# IMPORTANT: do NOT add `*.md` or `README.md` here — the Dockerfile COPYs
+# `README.md` and uv requires it to resolve the package metadata.
+
+.git
+.github
+.claude
+.pytest_cache
+.ruff_cache
+.venv
+.coverage
+**/__pycache__
+*.pyc
+tests
+docs

sengol-0.8.0/.github/copilot-instructions.md

@@ -0,0 +1,92 @@
+# GitHub Copilot — sengol (Phases 1–2)
+# .github/copilot-instructions.md
+
+## Project
+Sengol — Apache 2.0 Python 3.12 SDK for AI governance in regulated financial institutions.
+Building Phases 1–2: SDK core → OSFI E-23 compliance PDF report.
+
+## Always Suggest
+
+### Evaluator pattern (deterministic — no LLM)
+```python
+from sengol.core.evaluator import DeterministicEvaluator
+from sengol.core.types import LLMEvalInput, EvalScore
+
+class RequiredDisclosureEvaluator(DeterministicEvaluator):
+    """Checks OSFI E-23 required disclosure phrases are present. Observed at: Canadian retail bank."""
+    name = "RequiredDisclosureEvaluator"
+    failure_mode = "REQUIRED_DISCLOSURE_MISSING"
+    policies: list[str] = ["OSFI_E23"]    # list of str — not Literal
+
+    def evaluate(self, input: LLMEvalInput) -> EvalScore:
+        passed = "not a guarantee" in input.response.lower()
+        return EvalScore(
+            evaluator=self.name,
+            passed=passed,               # bool — always
+            failure_mode=None if passed else self.failure_mode,
+            reason="Disclosure present" if passed else "Missing required disclosure",
+        )
+```
+
+### LLM evaluator stub pattern (Phase 1)
+```python
+class FaithfulnessEvaluator(LLMEvaluator):
+    name = "FaithfulnessEvaluator"
+    failure_mode = "FAITHFULNESS_FAILURE"
+    policies: list[str] = ["OSFI_E23"]
+
+    async def evaluate_async(self, input: LLMEvalInput) -> EvalScore:
+        # Phase 1: stub — returns True
+        # Phase 3: wire real LLM judge here
+        return EvalScore(evaluator=self.name, passed=True, failure_mode=None)
+```
+
+### AuditRecord write (always sign before write)
+```python
+signed = record.sign(os.getenv("SENGOL_SIGNING_KEY"))
+await audit_store.write(signed)  # only write signed records
+# verify immediately after
+assert await audit_store.verify(signed.record_id)
+```
+
+### ControlBook-driven report
+```python
+# Always ControlBook-driven — works for any regulation
+report = ComplianceReportGenerator(
+    audit_store=audit_store,
+    controlbook=controlbook,  # loads from acme_controlbook.yaml
+).generate(agent_id="rag-advisor-001", period_from=..., period_to=...)
+# report.pdf_path — hand to CRO
+# report.json_path — machine-readable evidence
+```
+
+### Logging
+```python
+import structlog
+log = structlog.get_logger()
+log.info("eval.complete", evaluator="MyEval", passed=True, latency_ms=12)
+```
+
+## Never Suggest
+
+- `PolicyId = Literal["OSFI_E23", ...]` — it must be `str`
+- Float as `EvalScore.passed` — always `bool`
+- `print()` for logging — always `structlog`
+- Sequential LLM evaluator calls — always `asyncio.gather()`
+- `UPDATE` or `DELETE` on `audit_records` table
+- Hardcoded OSFI-only reports — use `ComplianceReportGenerator(controlbook=...)`
+- `import openai` — for judge calls, respect `ControlBook.judge_by_tier`
+
+## Test Pattern
+```python
+@pytest.mark.asyncio
+async def test_evaluator_fails_missing_disclosure():
+    ev = RequiredDisclosureEvaluator()
+    result = ev.evaluate(LLMEvalInput(
+        agent_id="test", agent_version="1.0",
+        prompt="What should I know?",
+        response="Buy this fund now.",  # missing disclosure
+    ))
+    assert result.passed is False
+    assert result.failure_mode == "REQUIRED_DISCLOSURE_MISSING"
+```

sengol-0.8.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.11
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Fast tests
+        run: uv run pytest -v -m "not llm and not integration"
+      - name: Generate OpenAPI spec
+        env:
+          SENGOL_SIGNING_KEY: ci-placeholder
+          SENGOL_AUDIT_URI: memory://
+        run: |
+          uv run python -c "
+          import yaml
+          from sengol.api.app import app
+          with open('sengol/api/openapi_ci.yaml', 'w') as f:
+              yaml.safe_dump(app.openapi(), f, sort_keys=False, allow_unicode=True, width=120)
+          "
+      - name: Check for breaking API changes (ADR-0057)
+        uses: tufin/oasdiff-action@v1
+        with:
+          base: sengol/api/openapi.yaml
+          revision: sengol/api/openapi_ci.yaml
+          fail-on-diff: breaking
+
+  terraform-plan:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: terraform/aws
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: "1.9.8"
+      - name: Terraform init
+        run: terraform init -backend=false -input=false
+      - name: Terraform validate
+        run: terraform validate
+      - name: Terraform fmt check
+        run: terraform fmt -check -recursive
+      - name: Terraform plan (no apply — mock credentials baked into providers.tf)
+        run: terraform plan -var-file=environments/dev.tfvars -input=false
+
+  frontend:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: console
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: console/package-lock.json
+      - name: Install dependencies
+        run: npm ci
+      - name: Test
+        run: npm test
+      - name: Build
+        run: npm run build

sengol-0.8.0/.github/workflows/deploy.yml

@@ -0,0 +1,86 @@
+name: Deploy
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: "Target environment"
+        required: true
+        default: staging
+        type: choice
+        options:
+          - dev
+          - staging
+          - production
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    name: Deploy to ${{ github.event_name == 'workflow_dispatch' && inputs.environment || 'staging' }}
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment || 'staging' }}
+
+    env:
+      DEPLOY_ENV: ${{ github.event_name == 'workflow_dispatch' && inputs.environment || 'staging' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+          aws-region: ${{ secrets.KUBE_CLUSTER_REGION }}
+
+      - name: Login to Amazon ECR
+        id: ecr-login
+        uses: aws-actions/amazon-ecr-login@v2
+
+      - name: Build and push Docker image to ECR
+        env:
+          IMAGE_URI: ${{ secrets.ECR_REGISTRY }}/${{ secrets.ECR_REPOSITORY }}:${{ github.sha }}
+        run: |
+          docker build -t "${IMAGE_URI}" .
+          docker push "${IMAGE_URI}"
+          echo "image_uri=${IMAGE_URI}" >> "${GITHUB_OUTPUT}"
+        id: build
+
+      - name: Set up kubectl
+        uses: azure/setup-kubectl@v3
+
+      - name: Set up Helm
+        uses: azure/setup-helm@v3
+        with:
+          version: v3.14.0
+
+      - name: Update kubeconfig for EKS
+        run: |
+          aws eks update-kubeconfig \
+            --name ${{ secrets.KUBE_CLUSTER_NAME }} \
+            --region ${{ secrets.KUBE_CLUSTER_REGION }}
+
+      - name: Helm upgrade/install
+        run: |
+          helm upgrade --install sengol ./helm/sengol \
+            --namespace sengol \
+            --create-namespace \
+            -f helm/sengol/values-aws.yaml \
+            --set image.repository=${{ secrets.ECR_REGISTRY }}/${{ secrets.ECR_REPOSITORY }} \
+            --set image.tag=${{ github.sha }} \
+            --set secrets.SENGOL_SIGNING_KEY="${{ secrets.SENGOL_SIGNING_KEY }}" \
+            --set secrets.SENGOL_KMS_KEY_ID="${{ secrets.SENGOL_KMS_KEY_ID }}" \
+            --set config.SENGOL_AWS_REGION=${{ secrets.KUBE_CLUSTER_REGION }} \
+            --wait --timeout 5m
+
+      - name: Smoke test
+        run: |
+          SENGOL_URL="${{ secrets.SENGOL_URL }}"
+          curl --fail --retry 3 --retry-delay 5 "${SENGOL_URL}/health"
+          echo "Smoke test passed"

sengol-0.8.0/.github/workflows/integration.yml

@@ -0,0 +1,70 @@
+name: Integration tests (Postgres)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'sengol/core/types.py'
+      - 'sengol/governance/audit_store.py'
+      - 'sengol/governance/gold_score_store.py'
+      - 'sengol/governance/saturation_store.py'
+      - 'sengol/governance/report_base.py'
+      - 'sengol/cli/main.py'
+      - 'sengol/logging.py'
+      - 'alembic/**'
+      - 'tests/integration/**'
+  pull_request:
+    paths:
+      - 'sengol/core/types.py'
+      - 'sengol/governance/audit_store.py'
+      - 'sengol/governance/gold_score_store.py'
+      - 'sengol/governance/saturation_store.py'
+      - 'sengol/governance/report_base.py'
+      - 'sengol/cli/main.py'
+      - 'sengol/logging.py'
+      - 'alembic/**'
+      - 'tests/integration/**'
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: sengol
+          POSTGRES_PASSWORD: sengol
+          POSTGRES_DB: sengol_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      SENGOL_AUDIT_URI: postgresql+asyncpg://sengol:sengol@localhost:5432/sengol_test
+      SENGOL_SIGNING_KEY: test-signing-key-32-bytes-minimum
+      SENGOL_ENVIRONMENT: development
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run Alembic migrations
+        run: uv run alembic upgrade head
+
+      - name: Run integration tests
+        run: uv run pytest tests/integration/ -v --tb=short -m integration

sengol-0.8.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write  # required for PyPI OIDC trusted publisher
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish
+        # uv publish defaults to PyPI and auto-uses the OIDC token from Actions.
+        # No UV_PUBLISH_URL or UV_PUBLISH_TOKEN needed.
+        #
+        # One-time setup required on pypi.org (per account):
+        # Account -> Publishing -> Add pending publisher
+        #   GitHub owner: sengol-io
+        #   repo:         sengol
+        #   workflow:     publish.yml

sengol-0.8.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+/build/
+/dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.hypothesis/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Secrets / env
+.env
+.env.local
+*.pem
+
+# Demo + run artifacts (regenerated by examples/demo_end_to_end.py)
+/reports/
+/datasets/
+/eval-results.xml
+
+# Claude (local settings stay ignored; versioned skills are tracked)
+.claude/*
+!.claude/skills/
+
+# Console frontend (built assets ship in wheel, not committed)
+console/node_modules/
+sengol/console_static/
+console/*.tsbuildinfo

sengol-0.8.0/.mcp.json

@@ -0,0 +1,30 @@
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+      "description": "Read sengol.yaml, catalog.yaml, source files"
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" },
+      "description": "Create PRs, manage issues, read commits"
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres", "${SENGOL_AUDIT_URI}"],
+      "description": "Query AuditStore, verify HMAC records"
+    },
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "description": "Persist phase state across Claude Code sessions"
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+      "description": "Multi-step phase builds — plan before implementing"
+    }
+  }
+}