prismlib-plus 0.7.0__tar.gz

prismlib_plus-0.7.0/BENCHMARK_RESULTS.md

@@ -0,0 +1,119 @@
+# PrismLib — Benchmark Results (single source of truth)
+
+All numbers below are from **real runs**. Two environments:
+
+- **Cache & Driver layers** — Azure Container Apps (westus2), concurrent load test
+- **Cluster mesh** — Azure Container Apps (westus2), 3 nodes across 2 VNets
+
+Raw data:
+- `benchmark/results/prism_mixed_*_report.json`, `prism_light_*_report.json` (cache)
+- `benchmark/results/driver_benchmark_azure.json` (driver e2e, latest)
+- `benchmark/results/driver_benchmark_*.json` (driver history)
+- `benchmark/cluster/cluster_benchmark_results_azure.json` (cluster mesh)
+- `benchmark/cluster/cluster_benchmark_results_loopback.json` (earlier loopback run, for reference)
+
+---
+
+## 1. PrismCache — semantic LLM cache (Azure, concurrent load)
+
+| Scenario | Users | Duration | Queries | Hit rate | Tokens saved | Monthly est. saved |
+|----------|-------|----------|---------|----------|--------------|--------------------|
+| Light | 20 | 60 s | 4,050 | 91.0–92.0% | 953,344 | ~$412 |
+| Mixed | 50 | 300 s | 6,973 | **95.9%** | 1,673,216 | ~$723 |
+
+Avg hit latency ~291 ms, avg miss latency ~415 ms (mixed scenario).
+
+## 2. PrismDriver — WAL-streamed DB driver (Azure, 2-container e2e)
+
+**Deploy:** `deploy/azure_driver_run.ps1` (or `.sh`)  
+**Topology:** `prism-wrapper-sim` (DB node) + `prism-benchmark` (app node with Python PrismDriver)  
+**Latest run:** 2026-06-29 — `benchmark/results/driver_benchmark_azure.json`  
+**Logs:** `benchmark/results/azure_e2e_logs/`
+
+| Path | Avg read latency | Result |
+|------|------------------|--------|
+| Baseline (network to DB) | 118.5 ms | — |
+| PrismDriver (local index, Python mode) | **0.27 ms** | **439× faster · 99.8% latency reduction** |
+
+20 concurrent users × 45 s/phase, 1,000-row catalog, WAL subscribe warmup ~51k rows/s ingest.  
+Driver mode: `python` (C++ DLL not built in OSS repo).
+
+**Container URLs (rg-prism-driver-e2e, westus2):**
+- App: `https://prism-benchmark.gentlesmoke-8bb70e10.westus2.azurecontainerapps.io`
+- DB:  `https://prism-wrapper-sim.gentlesmoke-8bb70e10.westus2.azurecontainerapps.io`
+
+Previous run (2026-06-24): 70.7× / 2.02 ms driver / 142.8 ms baseline — `driver_benchmark_20260624_135338.json`.
+
+---
+
+## 3. Cluster mesh — 3 nodes, Azure Container Apps, 2 VNets (westus2)
+
+Topology: GREEN + BLUE in Environment A (one VNet), ORANGE in Environment B
+(separate VNet), benchmark runner external/cross-network.
+Deploy: `deploy/azure_cluster_run.sh`.
+
+### 3.1 Token savings
+
+| Node | Role | Network | Tokens billed | Tokens saved | Mechanism | Per-node savings |
+|------|------|---------|---------------|--------------|-----------|------------------|
+| node-green | active | same VNet | 328 | 130 | context compression | 28.4% |
+| node-blue | warm standby | same VNet | 0 | 61 | cluster cache | 100% |
+| node-orange | reserve | cross-VNet | 0 | 75 | cluster cache | 100% |
+| **Cluster avg** | | | | | | **76.1%** |
+
+> Note: 76.1% is the arithmetic mean of per-node savings under a workload where
+> warm nodes receive already-answered queries. Conservative reading: savings on
+> a node = (fraction of its queries already answered elsewhere) + 28–64%
+> compression on the rest. High-repeat workloads trend toward the cache figure;
+> low-repeat toward the compression-only figure.
+
+### 3.2 CHORUS frame latency (cross-VNet, same region)
+
+| Node | Network | Avg | Min | Max |
+|------|---------|-----|-----|-----|
+| node-green | same VNet | 19.4 ms | 15.0 ms | 29.0 ms |
+| node-blue | same VNet | 19.9 ms | 15.2 ms | 22.6 ms |
+| node-orange | cross-VNet | 21.6 ms | 16.0 ms | 26.3 ms |
+
+### 3.3 Health-alert propagation
+
+| Event | Source → Dest | Network | Propagation |
+|-------|---------------|---------|-------------|
+| cpu_high (92%) | GREEN → BLUE | same VNet | 633 ms |
+| cpu_high (92%) | GREEN → ORANGE | cross-VNet | 674 ms |
+
+### 3.4 Failover (leaderless)
+
+| Metric | Value |
+|--------|-------|
+| GREEN silence threshold | 3,000 ms |
+| Failover detected | 3,960 ms |
+| Promotion to active (once detected) | 97 ms |
+| Human intervention | none |
+
+### 3.5 Context compression
+
+| Query | Tokens used | Tokens saved | Compression |
+|-------|-------------|--------------|-------------|
+| What is PrismLib? | 71 | 126 | 64.0% |
+| How does CHORUS Fabric work? | 85 | 118 | 58.1% |
+| Explain context compression. | 75 | 128 | 63.1% |
+| What is Blue/Green/Orange failover? | 84 | 116 | 58.0% |
+| How does token deduplication work? | 81 | 116 | 58.9% |
+| **Average** | | | **60.4%** |
+
+---
+
+## Scope & honesty notes
+
+- Driver e2e uses **wrapper-sim** (in-memory catalog), not production Postgres + `prism-wrapper`. Numbers are real for that topology; validate on your DB before SLAs.
+- Driver ran in **Python mode**; C++ DLL sources are not in the OSS repo.
+- The cluster ran across two VNets but **both in westus2** — cross-*region*
+  latency and network-partition behavior are untested.
+- Cluster benchmark is a **functional 3-node run** (5 queries), not a sustained
+  load test; the cache/driver layers (§1–2) are the load-tested ones.
+- Leaderless promotion trades Raft-style consensus guarantees for simplicity;
+  a partition could briefly produce two actives.
+- Loopback-vs-Azure: token savings and compression were identical (logic, not
+  network); only latency/alert/failover timings differ, and the Azure numbers
+  are the canonical ones above.

prismlib_plus-0.7.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to **prismlib-plus** (superset of [prismlib](https://pypi.org/project/prismlib/) on PyPI).
+
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+
+---
+
+## [0.7.0] — 2026-06-29
+
+### Azure-validated benchmarks
+
+- **PrismDriver 2-container e2e** (westus2): **118.5 ms → 0.27 ms** (439×, 99.8% latency reduction)
+  - Deploy: `deploy/azure_driver_run.ps1` / `.sh`
+  - Artifacts: `benchmark/results/driver_benchmark_azure.json`, `benchmark/results/azure_e2e_logs/`
+- **PrismCache** (Azure): 91–96% hit rate under concurrent load
+- **Cluster mesh** (Azure, 3 nodes / 2 VNets): 76% token savings, ~20 ms CHORUS latency, ~4 s failover
+
+### Enterprise & security
+
+- `PrismAPI` enterprise FastAPI stack: auth, rate limit, audit, `/health`, `/metrics`
+- mTLS on `WrapperGrpcServer` and `PrismDriver` gRPC client
+- `SECURITY.md` threat model; safe alert rules (no `eval`)
+- MCP server API-key gate (`PRISM_MCP_API_KEY`)
+- Helm chart with API-key secrets, TLS/mTLS projected volumes
+- `ENTERPRISE.md`, `examples/enterprise_server.py`, `enterprise_client.py`, Docker/compose
+
+### Correctness & driver
+
+- `LocalIndex` WAL upsert/update/delete by `row_id`
+- `RowEventHub`, HTTP subscribe server, gRPC `WrapperService` (Query/Write/Subscribe)
+- `prism.ffi.grpc_client` — remote Query/Write for Python driver
+- `PrismDriver` gRPC subscription + HTTP fallback (`PRISM_WRAPPER_URL`)
+- Fix: `LocalIndex.is_warm` now reflects ingested rows (was stale `_rows`)
+- Benchmark: `/driver/reset-baseline` preserves warm index between phases
+
+### Observability
+
+- Prometheus metrics registry; optional OpenTelemetry spans on cache + API client
+- `ClusterTransport`, `HealthMonitor`, cluster cache invalidation hooks
+
+### Tests
+
+- 217+ tests: enterprise, security, cluster, gRPC client, MCP auth
+
+---
+
+## [0.6.0] — 2026-06 (internal)
+
+- Initial enterprise tier implementation (auth, gRPC wrapper, observability scaffolding)
+- Version bump in repo; not published to PyPI
+
+---
+
+## PyPI lineage
+
+| Package | PyPI version | Source |
+|---------|--------------|--------|
+| `prismlib` | **0.4.0** (latest on PyPI) | [PrismLib](https://github.com/insightitsGit/prismlib) — cache, driver, cluster core |
+| `prismlib-plus` | **0.7.0** (this release) | PrismLabPlusAPI — prismlib + PrismAPI + enterprise |
+
+Install the superset:
+
+```bash
+pip install "prismlib-plus[enterprise,cache,fabric]"
+```
+
+To publish as an upgrade to the existing package name, see `RELEASE.md` (optional `prismlib` 0.5.0 rename).
+
+**User-facing release announcement:** [RELEASE_NOTES.md](RELEASE_NOTES.md)

prismlib_plus-0.7.0/ENTERPRISE.md

@@ -0,0 +1,126 @@
+# Enterprise deployment guide
+
+PrismLib Plus (`prismlib-plus` 0.7.0) ships an enterprise HTTP API layer (PrismAPI), optional gRPC wrapper, auth, rate limiting, audit logging, Prometheus metrics, and optional OpenTelemetry tracing.
+
+## Quick start (local)
+
+```bash
+pip install -e ".[enterprise,cache,fabric]"
+
+# Terminal 1 — API server (prints a dev API key)
+python examples/enterprise_server.py
+
+# Terminal 2 — HTTP client
+export PRISM_API_KEY=<key-from-server>
+python examples/enterprise_client.py --query "return policy"
+```
+
+Loopback golden path (no network):
+
+```bash
+python examples/enterprise_golden_path.py
+```
+
+## Docker
+
+```bash
+export PRISM_API_KEYS="$(python -c 'from prism.api import generate_api_key; print(generate_api_key())')"
+docker compose -f deploy/docker-compose.enterprise.yml up --build
+
+PRISM_API_KEY=$PRISM_API_KEYS python examples/enterprise_client.py
+```
+
+Image build only:
+
+```bash
+docker build -f deploy/Dockerfile.enterprise -t prismlib/enterprise:0.6.0 .
+```
+
+## Production environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `PRISM_API_KEYS` | Comma-separated API keys |
+| `PRISM_API_REQUIRE_AUTH` | `true` / `false` |
+| `PRISM_API_RATE_LIMIT_RPM` | Requests per minute per client |
+| `PRISM_TENANT_ID` | Tenant isolation for projection |
+| `PRISM_WRAPPER_TLS_CERT` | Server TLS certificate path |
+| `PRISM_WRAPPER_TLS_KEY` | Server TLS private key path |
+| `PRISM_WRAPPER_TLS_CA` | CA for mTLS client verification |
+| `PRISM_WRAPPER_REQUIRE_CLIENT_CERT` | Require client certs on gRPC |
+| `PRISM_DRIVER_TLS_CA` | Driver trust anchor |
+| `PRISM_DRIVER_TLS_CLIENT_CERT` | Driver client certificate |
+| `PRISM_DRIVER_TLS_CLIENT_KEY` | Driver client private key |
+| `PRISM_MCP_API_KEY` | MCP tool `api_key` gate |
+
+Generate dev mTLS certs (requires OpenSSL on PATH):
+
+```bash
+python scripts/gen_dev_certs.py --out certs/dev
+```
+
+## Kubernetes (Helm)
+
+```bash
+# Create secrets out-of-band (recommended)
+kubectl create secret generic prism-api-keys \
+  --from-literal=PRISM_API_KEYS="$(python -c 'from prism.api import generate_api_key; print(generate_api_key())')"
+
+kubectl create secret tls prism-tls --cert=tls.crt --key=tls.key
+kubectl create secret generic prism-mtls-ca --from-file=ca.crt=ca.pem
+
+helm upgrade --install prismlib deploy/helm/prismlib \
+  --set image.repository=prismlib/enterprise \
+  --set image.tag=0.6.0 \
+  --set auth.apiKeySecret=prism-api-keys \
+  --set tls.certSecret=prism-tls \
+  --set tls.caSecret=prism-mtls-ca
+```
+
+Endpoints:
+
+- `POST /chorus/search` — CHORUS binary frames (`Content-Type: application/x-chorus-frame`)
+- `GET /health` — liveness
+- `GET /metrics` — Prometheus scrape target
+- `GET /audit/recent` — last 100 security events
+
+## gRPC wrapper (optional sidecar)
+
+Run the DB-node wrapper daemon with mTLS:
+
+```bash
+export PRISM_WRAPPER_TLS_CERT=certs/dev/server.crt
+export PRISM_WRAPPER_TLS_KEY=certs/dev/server.key
+export PRISM_WRAPPER_TLS_CA=certs/dev/ca.pem
+prism-wrapper --grpc-port 50051
+```
+
+Python driver remote query uses `WrapperService.Query` when gRPC stubs are installed.
+
+## Observability
+
+Prometheus metrics are always available at `/metrics`.
+
+OpenTelemetry (optional):
+
+```bash
+pip install "prismlib-plus[otel]"
+```
+
+```python
+from prism.observability.otel import configure_tracing
+configure_tracing("my-service", otlp_endpoint="http://otel-collector:4317")
+```
+
+Spans are emitted for `PrismCache.get_or_call` and `PrismAPIClient.query`.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for the threat model, TLS defaults, and audit log fields.
+
+## MCP server
+
+```bash
+export PRISM_MCP_API_KEY=your-key
+python -m prism.api.mcp  # pass api_key in tool arguments when auth enabled
+```

prismlib_plus-0.7.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include RELEASE_NOTES.md
+include SECURITY.md
+include ENTERPRISE.md
+include RESULTS_AND_IMPROVEMENTS.md
+include BENCHMARK_RESULTS.md
+recursive-include proto *.proto