Metadata-Version: 2.4
Name: sovereign-core
Version: 1.0.1
Summary: Core schemas and protocols for Sovereign Systems
Author-email: kenwalger <kenalger@comcast.net>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kenwalger/sovereign-sdk
Project-URL: Repository, https://github.com/kenwalger/sovereign-sdk
Project-URL: Changelog, https://github.com/kenwalger/sovereign-sdk/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=48.0.0
Requires-Dist: pydantic>=2.7.0

# Sovereign Systems SDK

**High-Integrity Cryptographic Provenance and Inbound Protection Boundaries for Agentic Workflows.**

Sovereign Systems is a local-first AI WAF and compliance gate. It intercepts every inbound payload before it reaches a model or agentic loop, strips high-entropy boilerplate, and seals the result with an Ed25519-signed `ForensicReceipt` that gives enterprise auditors mathematical proof of un-tampered boundary transformation — all running on local silicon with no external service dependency.

Every boundary crossing produces a non-repudiable chain of custody: the receipt binds the sieved payload hash and the full transformation accounting inside a single cryptographic envelope. No post-hoc mutation of the output or its metrics can go undetected.

To learn more about the philosophy and reasoning behind this project, see [PHILOSOPHY.md](PHILOSOPHY.md).

---

## Why an AI WAF?

Modern agentic pipelines ingest user intent through prompt text. That text is routinely bloated with conversational filler — greetings, hedging adverbs, redundant preambles — that inflates token budgets and introduces non-deterministic reasoning noise without contributing semantic content. At the same time, enterprises operating LLM workloads need the same compliance guarantees they expect from a network WAF: proof that payloads were inspected, proof that the inspection was faithful, and an append-only audit log that is tamper-evident after the fact.

Sovereign Systems provides both:

- **Inbound boundary enforcement** — every payload is sieved before a model or tool sees it.
- **Cryptographic chain of custody** — every sieved payload is sealed with a node-local Ed25519 private key into a `ForensicReceipt` that persists forever.
- **Non-repudiation** — the receipt covers the output hash and the transformation accounting under the same signature, so neither the result nor the metrics can be altered without breaking verification.
- **Local-only execution** — no telemetry leaves the host; key material never leaves the node.

---

## Workspace Topography

This repository is managed as an integrated `uv` workspace separating the cryptographic data tier from the execution runtime:

```text
.
├── packages/
│   ├── sovereign-core/       # Pure data tier (zero high-compute dependencies)
│   │   └── src/sovereign_core/
│   │       ├── crypto.py     # Ed25519 key management & ForensicReceipt minting
│   │       └── gateway.py    # Prose Tax sieve & SovereignGateway high-level API
│   │
│   ├── sovereign-runtime/    # Compute/Execution tier (tool & model isolation)
│   │   └── src/sovereign_runtime/
│   │       ├── router.py     # Intent-based pre-flight namespace exposure
│   │       └── __main__.py   # Execution runtime entry point
│   │
│   └── sovereign-fastapi/    # FastAPI/Starlette ASGI middleware adapter
│       └── src/sovereign_fastapi/
│           └── middleware.py # SovereignMiddleware — sieve-and-sign request interceptor
│
├── pyproject.toml            # Monorepo configuration & workspace links
└── uv.lock                   # Deterministic dependency lockfile
```

---

## The ForensicReceipt: Sealed Transformation Accounting

Every boundary crossing produces a `ForensicReceipt`. Understanding its structure explains exactly what an enterprise auditor can prove from the output alone.

### What is sealed

The Ed25519 signature inside every receipt covers a single canonical manifest:

```json
{
  "metadata": { ... },
  "payload_hash": "<sha256-of-sieved-content>",
  "timestamp": "<utc-iso8601>"
}
```

`payload_hash` is the SHA-256 digest of the exact sieved string delivered to the model or tool. When the Prose Tax sieve is active, `metadata` always contains a `prose_tax_summary` sub-object:

```json
"prose_tax_summary": {
  "raw_token_count": 12,
  "optimized_token_count": 4,
  "tokens_eliminated": 8,
  "tax_savings_percentage": 66.6667,
  "total_tokens_saved": 8
}
```

Because `metadata` is bound inside the signed manifest, these token counts are just as tamper-evident as `payload_hash` itself. An auditor who holds only the node's public key can independently verify:

1. **Output integrity** — the sieved content hasn't been altered after signing (`payload_hash`).
2. **Transformation accounting** — the before/after token delta recorded at signing time hasn't been fabricated (`prose_tax_summary` is sealed under the same signature).
3. **Identity provenance** — the receipt was minted by the expected node, not a rogue keypair (`public_key` key-pin assertion).

Together these three checks give mathematical proof that the boundary transformation was faithful and un-tampered — equivalent to a signed audit log with built-in integrity verification.

### Verification workflow

```python
import asyncio
import json
from sovereign_core.gateway import SovereignGateway
from sovereign_core.crypto import SovereignKeyManager

async def main():
    gateway = SovereignGateway(signing_key=".keys/sovereign_identity.pem")
    result = await gateway.sieve_and_sign("Hi! Please just help me now.")

    # result.content == "help me now"
    # result.receipt["metadata"]["prose_tax_summary"]["tokens_eliminated"] == 4

    # Verify later — requires only the public key and the original sieved payload
    is_valid = SovereignKeyManager.verify_receipt(
        result.receipt,
        {"content": result.content},
        expected_public_key=gateway.export_public_key(),
    )
    assert is_valid  # fails if any field was mutated after signing

asyncio.run(main())
```

---

## Primary Developer Interface: `SovereignGateway`

`SovereignGateway` is the single entry point for application code. It wraps the full sieve-and-sign pipeline behind a clean four-method API.

### One-shot macro (recommended)

`sieve_and_sign()` strips Prose Tax boilerplate, fuses the transformation telemetry into the receipt metadata, and seals everything in a single awaitable call:

```python
import asyncio
from sovereign_core.gateway import SovereignGateway

async def main():
    gateway = SovereignGateway(signing_key=".keys/sovereign_identity.pem")
    result = await gateway.sieve_and_sign("Hi! Please just help me now.")

    # result  — SovereignBoundaryResponse (Pydantic model, fully typed)
    # result.content  — purified string, Prose Tax stripped ("help me now")
    # result.receipt  — ForensicReceipt with prose_tax_summary sealed inside

    print(result.content)
    print(result.receipt["payload_hash"])

asyncio.run(main())
```

Inside a FastAPI route the gateway instance lives on the application object; the route itself is already async:

```python
from sovereign_core.gateway import SovereignGateway

gateway = SovereignGateway(signing_key=".keys/sovereign_identity.pem")

@app.post("/api/v1/ingest")
async def handle_agent_input(raw_payload: dict):
    result = await gateway.sieve_and_sign(raw_payload["text"])

    await reasoning_ledger.append(
        payload=result.content,
        receipt=result.receipt,
    )
    return {
        "status": "sovereign_verified",
        "receipt_id": result.receipt["payload_hash"],
    }
```

### Granular two-step workflow

When the clean context is needed before signing (e.g. for intermediate validation or logging):

```python
import asyncio
from sovereign_core.gateway import SovereignGateway

async def main():
    gateway = SovereignGateway(signing_key=".keys/sovereign_identity.pem")

    # 1. Strip Prose Tax — remove boilerplate, normalize whitespace
    clean_context = await gateway.sieve("Hi! Please just help me now.")

    # 2. Cryptographically seal — transformation telemetry fused into metadata
    receipt = gateway.sign(clean_context)

    print(clean_context)            # "help me now"
    print(receipt["payload_hash"])  # SHA-256 of {"content": "help me now"}

asyncio.run(main())
```

### Independent receipt verification

Receipts produced by either workflow can be verified at any time using only the public key:

```python
from sovereign_core.crypto import SovereignKeyManager

is_valid = SovereignKeyManager.verify_receipt(
    receipt,
    {"content": clean_context},
    expected_public_key=gateway.export_public_key(),
)
```

---

## ASGI Middleware for FastAPI / Starlette

`SovereignMiddleware` applies the sieve-and-sign boundary to every inbound JSON request transparently, without changes to route handlers:

```python
from fastapi import FastAPI
from sovereign_fastapi.middleware import SovereignMiddleware

app = FastAPI()
app.add_middleware(
    SovereignMiddleware,
    signing_key=".keys/sovereign_identity.pem",
    payload_field="text",   # JSON key to sieve; omit to sieve the whole body
    strict_mode=False,      # True → return HTTP 422 on any interception error
)
```

The middleware:
1. Extracts the target field from the JSON body.
2. Calls `sieve_and_sign()` on the gateway.
3. Overwrites `request._body` so every downstream route handler sees the sieved payload.
4. Caches the sealed receipt at `request.state.sovereign_receipt`.
5. Injects `X-Sovereign-Receipt-Signature` and `X-Sovereign-Tokens-Saved` on the outbound response.

---

## Prose Tax Optimization

> **This feature is optional.** The cryptographic boundary and ForensicReceipt are produced whether or not any text is eliminated. Prose Tax optimization runs inside the audit envelope — every token count and savings metric is sealed alongside the output hash.

The sieve removes conversational boilerplate that inflates token budgets without contributing semantic content:

| Category | Examples stripped |
|---|---|
| Greeting tokens | `hi`, `hello`, `hey`, `greetings` |
| Hedging adverbs | `just`, `simply`, `actually`, `basically`, `probably` |
| Affirmation filler | `of course`, `certainly`, `absolutely`, `sure` |
| Preamble phrases | `I hope this`, `I hope that`, `I hope you` |
| Politeness tokens | `please`, `kindly` |

All patterns carry negative lookahead guards (e.g. `(?![-\w])`) so technical compound words (`hi-fi`, `just-in-time`, `certainly-not`) pass through unmarred.

---

## Local Development

### Bootstrap

```bash
uv sync
```

### Run tests

```bash
uv run pytest
```

### Run the sovereign-node runtime

```bash
uv run sovereign-node
```

---

## Running the Workspace Examples

### FastAPI Gateway Example

**1. Set your node secret** (required for Ed25519 key generation):

```bash
export SOVEREIGN_NODE_SECRET=your-local-secret   # Linux / macOS
$env:SOVEREIGN_NODE_SECRET = "your-local-secret"  # Windows PowerShell
```

**2. Start the example server:**

```bash
uv run uvicorn examples.fastapi_gateway.app:app --reload
```

The server starts on `http://127.0.0.1:8000`. On first boot it generates an Ed25519 keypair at `.keys/example_identity.pem`.

**3. In a second terminal, run the example client:**

```bash
uv run python examples/fastapi_gateway/client.py
```

### Verifying a ForensicReceipt (CLI)

Export a receipt and the gateway's public key:

```python
import asyncio
import json
from sovereign_core.gateway import SovereignGateway

async def main():
    gateway = SovereignGateway()
    result = await gateway.sieve_and_sign("example payload")

    with open("receipt.json", "w") as f:
        json.dump(result.receipt, f, indent=2)

    print(gateway.export_public_key())

asyncio.run(main())
```

Verify the receipt:

```bash
uv run sovereign-verify \
    --receipt receipt.json \
    --public-key <base64-encoded-public-key>
```

On success:

```
Verified  ✓  payload_hash: 4fec03e7...
```

On tampered receipt:

```
Tampered  ✗  Receipt failed cryptographic verification.
  payload_hash : 4fec03e7...
  timestamp    : 2026-05-22T...
```

---

## Verification & Deep-Dive Diagnostics

### Local Environment Configuration

`SOVEREIGN_NODE_SECRET` can be specified in a `.env` file at the repository root. The node entrypoint loads it automatically via `python-dotenv`:

```bash
echo 'SOVEREIGN_NODE_SECRET=your-local-secret' > .env
```

### Standalone Tool Analysis Mode

```bash
uv run sovereign-node --tool analyze
```

### Expected Console Output

```
====================================================
🟢 Sovereign Node initialization sequence successful.
====================================================
🔄 Dispatching single tool execution: 'analyze'...
⚠️ Standalone mode detected: Context empty. Hydrating baseline diagnostic state...

🔒 Authenticated Forensic Receipt Proof:
{
  "timestamp": "2026-05-22T15:00:00.000000+00:00",
  "payload_hash": "4fec03e7083cca73cfb1152ae1d941b5a5a581fc725a43b3ee7df1d9ce697954",
  "public_key": "<base64-encoded Ed25519 public key>",
  "signature": "<base64-encoded Ed25519 signature>",
  "metadata": {
    "runtime": "async-sovereign-node",
    "py_ver": "3.12.x",
    "execution_success": true
  }
}
```

**Line-by-line interpretation:**

| Output line | What it proves |
|---|---|
| `🟢 Sovereign Node initialization sequence successful.` | Ed25519 keypair loaded or generated; `SOVEREIGN_NODE_SECRET` resolved; router and session context initialised. |
| `⚠️ Standalone mode detected …` | The `analyze` tool detected no upstream context and self-hydrated a baseline telemetry stream — expected behaviour in single-tool invocations. |
| `"payload_hash": "4fec03e7…"` | SHA-256 digest of the deterministically serialised execution payload. |
| `"public_key": "<base64>"` | Base64-encoded raw Ed25519 public key; verified by `_audit_receipt` before process exit. |
| `"signature": "<base64>"` | Ed25519 signature over `{"metadata": …, "payload_hash": …, "timestamp": …}`. Any mutation of these fields after issuance causes `verify_receipt` to return `False`. |
| `"execution_success": true` | The tool completed without raising an exception; the receipt is audit-clean. |
