guardspine-local-council 2.0.0__tar.gz

guardspine_local_council-2.0.0/.github/CLA.md

@@ -0,0 +1,41 @@
+# GuardSpine Individual Contributor License Agreement (DRAFT - counsel review)
+
+Purpose: every contribution after this point must grant GuardSpine the right to
+relicense, so the no-CLA gap (the root cause of the aragossa problem) never
+recurs. Based on the Apache ICLA with an explicit relicense/sublicense grant.
+Wire a CLA-assistant bot (e.g., CLA Assistant) to enforce on new PRs.
+
+------------------------------------------------------------------------------
+GUARDSPINE INDIVIDUAL CONTRIBUTOR LICENSE AGREEMENT (v1)
+------------------------------------------------------------------------------
+
+Thank you for contributing to GuardSpine, Inc. ("Company"). This Agreement sets
+the terms under which You contribute. "Contribution" means any work of authorship
+You intentionally submit to a Company project.
+
+1. Copyright license. You grant Company and recipients of software distributed by
+   Company a perpetual, worldwide, non-exclusive, royalty-free, irrevocable
+   copyright license to reproduce, prepare derivative works of, publicly display,
+   sublicense, distribute, and RELICENSE Your Contributions and derivative works,
+   under ANY license terms Company selects, including non-open-source and
+   commercial terms.
+
+2. Patent license. You grant Company and recipients a perpetual, worldwide,
+   non-exclusive, royalty-free, irrevocable (except as below) patent license to
+   make, use, sell, offer to sell, import, and otherwise transfer Your
+   Contributions, for patent claims You can license that are necessarily
+   infringed by Your Contribution alone or combined with the project. If any
+   entity brings patent litigation alleging the Contribution infringes, the
+   patent licenses You granted for that Contribution terminate.
+
+3. Originality and rights. You represent each Contribution is Your original
+   creation and You are legally entitled to grant the above licenses. If Your
+   employer has rights to work You create, You represent You have permission to
+   contribute, or Your employer has waived such rights.
+
+4. Third-party material. If You submit work that is not Your original creation,
+   You will identify it and its license and any restrictions.
+
+5. No warranty. Contributions are provided "as is", without warranties.
+
+You: ____________________   GitHub user: ____________   Date: ______

guardspine_local_council-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install guardspine-kernel
+          pip install -e .
+          pip install pytest pytest-asyncio pytest-cov
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

guardspine_local_council-2.0.0/.github/workflows/cla.yml

@@ -0,0 +1,34 @@
+# CLA Assistant - enforces .github/CLA.md on every PR so the no-CLA gap
+# (root cause of the aragossa/PII-Shield ambiguity) cannot recur.
+#
+# BEFORE THIS WORKS, David must (repo settings, one-time):
+#   1. Create a fine-grained PAT with contents+PRs write, add as secret CLA_PAT.
+#   2. The action stores signatures in-repo at signatures/cla.json on main.
+# path-to-document auto-resolves to this repo via github.repository, so it keeps
+# working after the codeguard-action -> guardspine-code-action rename.
+name: CLA Assistant
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize]
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  statuses: write
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    steps:
+      - name: CLA Assistant
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        uses: contributor-assistant/github-action@v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_PAT }}
+        with:
+          path-to-signatures: 'signatures/cla.json'
+          path-to-document: '${{ github.server_url }}/${{ github.repository }}/blob/main/.github/CLA.md'
+          branch: 'main'
+          allowlist: DNYoussef,m1el,aragossa,dependabot[bot],*[bot]

guardspine_local_council-2.0.0/.github/workflows/codeguard.yml

@@ -0,0 +1,26 @@
+name: CodeGuard
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DNYoussef/codeguard-action@v1
+        id: codeguard
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          openrouter_api_key: ${{ secrets.OPENROUTER_API_KEY }}
+          risk_threshold: L3
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: evidence-bundle
+          path: .guardspine/bundles/

guardspine_local_council-2.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.env
+.venv/
+.DS_Store
+.pytest_cache/
+htmlcov/

guardspine_local_council-2.0.0/LICENSE

@@ -0,0 +1,100 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             GuardSpine, Inc.
+
+Licensed Work:        GuardSpine Local Council version 2.0.0.
+                      The Licensed Work is (c) 2026 GuardSpine, Inc.
+
+Additional Use Grant: You may make production use of the Licensed Work if your
+                      use is non-commercial, or is for evaluation or internal
+                      testing, or is by an organization with annual gross revenue
+                      below USD 1,000,000. Any other production use, and any use
+                      that offers the Licensed Work (or a service whose value
+                      derives primarily from it) to third parties for a fee,
+                      requires a commercial license from GuardSpine, Inc.
+
+Change Date:          Four years from the date each version of the Licensed Work
+                      is first published.
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact legal@guardspine.ai
+
+-----------------------------------------------------------------------------
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under the
+terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently
+in effect as described in this License, you must purchase a commercial license
+from the Licensor, its affiliated entities, or authorized resellers, or you must
+refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of
+the Licensed Work. If you receive the Licensed Work in original or modified form
+from a third party, the terms and conditions set forth in this License apply to
+your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor or
+its affiliates (provided that you may use a trademark or logo of Licensor as
+expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your
+works, and to refer to it using the trademark "Business Source License", as long
+as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business Source
+License" name and trademark, Licensor covenants to MariaDB, and to all other
+recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version, or
+   a license that is compatible with GPL Version 2.0 or a later version, where
+   "compatible" means that software provided under the Change License can be
+   included in a program with software provided under GPL Version 2.0 or a later
+   version. Licensor may specify additional Change Licenses without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as the
+   Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

guardspine_local_council-2.0.0/NOTICE

@@ -0,0 +1,16 @@
+NOTICE
+
+GuardSpine Local Council (c) 2026 GuardSpine, Inc.
+Licensed under the Business Source License 1.1. See LICENSE.
+
+This product includes PII-Shield (lib/pii-shield.wasm and integration code),
+authored by aragossa. PII-Shield was contributed under Apache License 2.0.
+A written confirmation that the PII-Shield code and the pii-shield.wasm binary
+may be redistributed under the Business Source License 1.1 is being obtained;
+until then those portions remain available under Apache License 2.0.
+
+This product depends on third-party Python packages installed via pip and used
+unmodified, each under its own license, including: PyGithub (LGPL-3.0),
+requests (Apache-2.0), PyYAML (MIT), unidiff (MIT), cryptography (Apache-2.0 /
+BSD-3-Clause), openai (Apache-2.0), anthropic (MIT), wasmtime (Apache-2.0),
+toml (MIT).

guardspine_local_council-2.0.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: guardspine-local-council
+Version: 2.0.0
+Summary: Local AI council review using Ollama -- no cloud API keys required
+Project-URL: Homepage, https://github.com/DNYoussef/guardspine-local-council
+License-Expression: BUSL-1.1
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.10
+Requires-Dist: guardspine-kernel>=0.2.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: wasmtime>=16.0.0
+Description-Content-Type: text/markdown
+
+# guardspine-local-council
+
+**Multi-model AI code review council -- local-first, cloud-optional.**
+
+Run multi-model code review councils on your machine using [Ollama](https://ollama.com), or connect to cloud providers (OpenAI, Anthropic, OpenRouter). Reviews produce cryptographically chained evidence bundles compatible with the GuardSpine ecosystem.
+
+## Requirements
+
+- Python 3.10+
+- [Ollama](https://ollama.com) running locally (`ollama serve`) for local-only use
+- At least one model pulled (e.g. `ollama pull llama3.1`)
+
+## Install
+
+```bash
+pip install guardspine-local-council
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/DNYoussef/guardspine-local-council.git
+cd guardspine-local-council
+pip install -e .
+```
+
+### Dependencies
+
+- **guardspine-kernel** (>=0.2.0) -- Canonical JSON hashing (RFC 8785) and content hash computation. Ensures cross-language parity with the TypeScript `@guardspine/kernel`.
+- **httpx** (>=0.24.0) -- Async HTTP client for Ollama and cloud API calls.
+- **wasmtime** (>=16.0.0) -- WASM runtime for the built-in PII-Shield sanitizer.
+
+## Quick Start
+
+```python
+import asyncio
+from guardspine_local_council import LocalCouncil, OllamaProvider, ReviewRequest
+
+async def main():
+    providers = [
+        OllamaProvider(model="llama3.1", reviewer_id="reviewer-a"),
+        OllamaProvider(model="llama3.1", reviewer_id="reviewer-b"),
+        OllamaProvider(model="llama3.1", reviewer_id="reviewer-c"),
+    ]
+
+    council = LocalCouncil(providers, quorum=2, consensus_threshold=0.66)
+
+    request = ReviewRequest(
+        artifact_id="my-function",
+        artifact_type="python-function",
+        content="def add(a, b): return a + b",
+    )
+
+    result = await council.review(request)
+    print(f"Decision: {result.consensus_decision} ({result.consensus_confidence})")
+
+asyncio.run(main())
+```
+
+## How It Works
+
+1. You create provider instances (Ollama, OpenAI, Anthropic, or OpenRouter).
+2. `LocalCouncil` sanitizes the review prompt through the built-in PII-Shield WASM module.
+3. The sanitized prompt is sent to all providers in parallel.
+4. Each provider returns a structured vote (approve/reject/abstain + confidence + findings).
+5. `SimpleAggregator` computes a confidence-weighted majority decision.
+6. Quorum and consensus threshold checks determine the final result.
+7. An evidence bundle is produced with a SHA-256 hash chain for tamper detection.
+
+## Providers
+
+Four providers are included. All implement the `ReviewProvider` protocol and return `ReviewVote` objects.
+
+### OllamaProvider (local, no API key)
+
+```python
+from guardspine_local_council import OllamaProvider
+
+provider = OllamaProvider(
+    model="llama3.1",           # Any Ollama model
+    base_url="http://localhost:11434",  # Ollama API endpoint
+    reviewer_id="local-1",
+)
+```
+
+Uses Ollama's `/api/generate` endpoint with JSON format mode. Falls back to abstain on parse failure.
+
+### OpenAIProvider
+
+```python
+from guardspine_local_council import OpenAIProvider
+
+provider = OpenAIProvider(
+    model="gpt-4o",
+    api_key="sk-...",  # or set OPENAI_API_KEY env var
+)
+```
+
+### AnthropicProvider
+
+```python
+from guardspine_local_council import AnthropicProvider
+
+provider = AnthropicProvider(
+    model="claude-sonnet-4-5-20250929",
+    api_key="sk-ant-...",  # or set ANTHROPIC_API_KEY env var
+)
+```
+
+### OpenRouterProvider
+
+```python
+from guardspine_local_council import OpenRouterProvider
+
+provider = OpenRouterProvider(
+    model="openrouter/auto",  # or any model on OpenRouter
+    api_key="sk-or-...",      # or set OPENROUTER_API_KEY env var
+)
+```
+
+You can mix providers freely. A council of 1 Ollama + 1 OpenAI + 1 Anthropic model works.
+
+## Council Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `providers` | (required) | List of `ReviewProvider` instances |
+| `hooks` | `[]` | Optional list of `ReviewHook` instances for pre/post processing |
+| `sanitizer` | `None` | Optional external sanitizer (in addition to built-in WASM) |
+| `quorum` | `3` | Minimum non-abstain votes required |
+| `consensus_threshold` | `0.66` | Minimum weighted confidence for a decision |
+| `sanitization_salt_fingerprint` | `sha256:00000000` | Non-secret salt fingerprint for sanitization attestations |
+
+## Review Modes
+
+### Single Review
+
+`council.review(request)` sends one prompt to all providers in parallel and returns a `CouncilResult` with the aggregated decision.
+
+### Rubric Review
+
+`council.rubric_review(request, rubric)` reviews code against a specific rubric. Providers run sequentially (VRAM constraint for local models). Returns a list of `ReviewVote` objects.
+
+```python
+from guardspine_local_council import RubricContext
+
+rubric = RubricContext(
+    rubric_name="input-validation",
+    description="All user input must be validated before use",
+    violations=[  # from a deterministic scanner
+        {"severity": "high", "rule_id": "IV-001", "file": "api.py", "line_number": 42,
+         "description": "Unvalidated query parameter"}
+    ],
+)
+
+votes = await council.rubric_review(request, rubric)
+```
+
+### Full Audit
+
+`council.full_audit(request, rubrics)` runs all providers against all rubrics and aggregates into an `AuditResult`. Each rubric gets a pass/fail/needs-review verdict via 2-of-3 majority. The overall decision rejects if any rubric with critical findings fails.
+
+```python
+result = await council.full_audit(request, rubrics)
+print(result.overall_decision)  # "approve" | "reject" | "needs-review"
+print(result.summary)
+
+# Pivot findings from rubric-oriented to file-oriented
+for filename, report in result.by_file().items():
+    print(f"{filename}: {report.critical_count} critical findings")
+```
+
+## Hooks
+
+Hooks run deterministically around review calls. The models never call MCP tools themselves -- hooks enrich prompts before the model sees them and validate output after.
+
+### SequentialThinkingHook
+
+Connects to `@modelcontextprotocol/server-sequential-thinking` via stdio. Decomposes each rubric into 5 structured reasoning steps and prepends a chain-of-thought scaffold to the prompt.
+
+```python
+from guardspine_local_council import SequentialThinkingHook
+
+hook = SequentialThinkingHook(num_steps=5)
+
+council = LocalCouncil(providers, hooks=[hook])
+await council.start_hooks()
+result = await council.full_audit(request, rubrics)
+await council.close_hooks()
+```
+
+### MCPClientHook
+
+Generic hook that calls any MCP server's tool to enrich prompts. Useful for injecting library docs, past findings, or external context.
+
+```python
+from guardspine_local_council import MCPClientHook
+
+hook = MCPClientHook(
+    name="memory",
+    server_command=["python", "-m", "memory_mcp"],
+    tool_name="recall",
+)
+```
+
+## PII-Shield Integration
+
+All review prompts pass through a built-in PII-Shield WASM module (`lib/pii-shield.wasm`) before reaching any model. This strips API keys, credentials, and PII from code submitted for review.
+
+The WASM module runs via `wasmtime` using temporary files for stdin/stdout. The Engine and Module are cached as a singleton; only the Store is recreated per call.
+
+**Fail-closed by default**: if the WASM module fails, the review raises `RuntimeError` rather than sending unsanitized content. Set `GUARDSPINE_PII_FAIL_OPEN=1` to override (not recommended for production).
+
+You can also provide an additional external sanitizer via the `sanitizer` parameter on `LocalCouncil`. Both stages are tracked in the evidence bundle's `sanitization` attestation block.
+
+## Evidence Bundle Output
+
+Council reviews produce v0.2.x evidence bundles containing:
+
+- Individual reviewer votes with confidence scores
+- Consensus decision and rationale
+- SHA-256 hash chain with immutability proof (using `guardspine-kernel` for canonical JSON hashing)
+- Optional `sanitization` attestation metadata (v0.2.1 format when sanitization occurred)
+
+```python
+result = await council.review(request)
+bundle = result.evidence_bundle
+
+print(f"Bundle ID: {bundle.bundle_id}")
+print(f"Version: {bundle.version}")  # "0.2.0" or "0.2.1"
+print(f"Root hash: {bundle.immutability_proof.root_hash}")
+
+# Verify with guardspine-verify
+import json
+with open("council-evidence.json", "w") as f:
+    json.dump(bundle.__dict__, f, default=str)
+# $ guardspine-verify council-evidence.json
+```
+
+Bundles are unsigned by default. For signed bundles, use GuardSpine Enterprise or provide a signing key via configuration.
+
+## Ollama Setup
+
+```bash
+# Check Ollama is running
+curl http://localhost:11434/api/tags
+
+# Pull models
+ollama pull llama3.1
+ollama pull codellama
+```
+
+The council returns abstain votes if a model is unavailable.
+
+## Data Types
+
+| Type | Purpose |
+|------|---------|
+| `ReviewRequest` | Input: artifact ID, type, content, optional context and risk tier hint |
+| `ReviewVote` | One reviewer's decision (approve/reject/abstain), confidence, rationale, findings |
+| `CouncilResult` | Aggregated result with votes, consensus, dissent, quorum status, evidence bundle |
+| `RubricContext` | Scanner-produced rubric with name, description, and violations |
+| `RubricVerdict` | Per-rubric result: pass/fail/needs-review with critical findings |
+| `AuditResult` | Full audit result across all rubrics with overall decision |
+| `FileFinding` | Single finding attributed to a specific file (for `by_file()` pivot) |
+| `FileReport` | All findings for one file, with `critical_count` property |
+| `EvidenceBundle` | v0.2.x bundle with items, hash chain, and optional sanitization |
+
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [guardspine-kernel-py](https://github.com/DNYoussef/guardspine-kernel-py) | Python kernel: canonical hashing, content hash (required dependency) |
+| [@guardspine/kernel](https://github.com/DNYoussef/guardspine-kernel) | TypeScript kernel (cross-language parity) |
+| [guardspine-verify](https://github.com/DNYoussef/guardspine-verify) | Verify council evidence bundles offline |
+| [guardspine-spec](https://github.com/DNYoussef/guardspine-spec) | Bundle specification (v0.2.1) |
+| [codeguard-action](https://github.com/DNYoussef/codeguard-action) | GitHub Action for automated code review |
+
+## License
+
+Business Source License 1.1 (source-available) -- see [LICENSE](LICENSE). Free for non-commercial, evaluation, and small-organization use (annual revenue under USD 1,000,000); other production use requires a commercial license from GuardSpine, Inc. Each version converts to Apache-2.0 four years after its release.