Metadata-Version: 2.4
Name: esgf-sdk
Version: 1.0.0
Summary: ESGF Governance SDK — Cryptographic AI Decision Ledger
Home-page: https://edgescoreai.com
Author: ESGF-X
Author-email: support@edgescoreai.com
License: Proprietary
Project-URL: Documentation, https://edgescoreai.com/docs
Project-URL: Repository, https://github.com/hadesofbaerlon/ESGF-X
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: cryptography>=43.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ESGF-X: Enterprise AI Governance Infrastructure

## Cryptographic Ledger + Revenue Model + Phase 4 Complete

**Status:** Phase 1 ✓ | Phase 2 ✓ | Phase 3 ✓ | Phase 4 ✓ (Complete as of March 19, 2026)
**Tests:** 212 passing / 212 total (100%) | **Baseline:** Established March 8, 2026 | **Deployment:** railway.toml configured
**System:** AGENT.md v2 (updated with .amp/amp.md doctrine reference) | **Billing:** billing/ package created
**Production Ready:**
  - Backend: `server.py` (30+ endpoints, Stripe integration, JWT auth, 7-role RBAC, tier gating, HMAC-signed decisions)
  - Frontend: `static/landing.html` (`/`), `static/demo.html` (`/demo`), `static/index.html` (`/app`) — customer-facing marketing pages plus the React SPA dashboard
  - Compliance: `esgf_compliance.py` (EU AI Act Article 11 template, Stripe-metered report generation)
  - Resilience: `governed_decorator.py` — PolicyCache (<0.1ms hits), CircuitBreaker (CLOSED/OPEN/HALF_OPEN), governance coverage scanner

---

## QUICK START

**System Status:** Production-ready. Benchmarks established. Ready to deploy.

### Verify It Works
```bash
python3 -m pytest --tb=short -q
```
Expected: 212 tests pass

### View Performance Baseline
```bash
cat .benchmark_baseline.json
```
**Baseline Data (March 8, 2026):**
- Engine p99: 1.186ms (SLA <5ms)
- Ledger p99: 0.494ms (SLA <3ms)
- Queue p99: 0.001ms (SLA <0.5ms)
- Billing p99: 0.002ms (SLA <0.1ms)

### Understand the System (Pick Your Path)

#### For Engineers
1. Read `AGENT.md` — Operating doctrine + phase gates (required)
2. Review `governance/engine.py` — Decision routing logic
3. Review `governance/ledger.py` — Ed25519 signing + Merkle chaining
4. Run tests: `bash run_all_tests.sh`
5. Start with test examples in `test_*.py`

#### For Business
1. Read section below: "THE PRODUCT" + "THE REVENUE MODEL"
2. Three-tier SaaS: Starter ($2.5K/mo), Professional ($6.5K/mo), Enterprise (custom)
3. Unit economics: ~$200K/year customer TCO → $2.5K-18K/month revenue
4. Go-to-market: Design partner pilots (30-day, $2,500 each)
5. Target launch: Week 1 (Q1 2026)

#### For Designers
1. Guardian Dashboard is live at `/app` (lime green / blood red theme):
   - AutoDemo, customer dashboard, owner dashboard, tenant login
   - Real-time ledger metrics (throughput, latency, tier usage)
   - Compliance report status and billing/usage breakdown by tier
2. Landing page at `/` — marketing entry point
3. Reference: `static/landing.html`, `static/demo.html`, and `static/index.html` for the shipped web surface; `governance/engine.py` for metrics output

#### For Sales
1. Pitch: Compliance automation → audit cycle reduced from 8 weeks to 2
2. TCO comparison: Manual audit ($200K) vs ESGF-X ($2.5K-18K/mo)
3. Entry point: 30-day pilot ($2,500) → SaaS conversion
4. Territory: Enterprise AI (finance, healthcare, insurance)
5. Sales deck template: See `docs/SALES_TEMPLATES.md` revenue section

---

## WHAT THIS SYSTEM DOES

### The Product (Phase 1)
Cryptographic governance ledger for enterprise AI models.

**What happens when a customer integrates:**
1. Wrap model with @governed decorator
2. Every inference is signed with Ed25519
3. Signature proves to auditors: "This inference happened, and here's the evidence"
4. Compliance audit takes 2 weeks instead of 8 weeks
5. Regulatory risk drops by 80%

**Value prop:**
- Manual compliance = 200+ hours/year, $200K+ audit cost
- ESGF-X = $2,500-$18,000/month (depending on tier)
- ROI: Pays for itself in one audit cycle

### The Revenue Model (Pillar)
Three parallel revenue streams:

1. **Design Partner Pilots ($2,500 each, 30-day contracts)**
   - 3 slots available
   - Customer wraps 3-5 models
   - You provide infrastructure + support
   - Converts to SaaS after pilot if successful

2. **SaaS Tiers ($2,500-$18,000/month)**
   - Starter: 50K traces/month
   - Professional: 500K traces/month
   - Enterprise: Unlimited, priority queue <10ms SLA

3. **Professional Services (Optional)**
   - Custom policy development
   - Compliance report generation
   - Audit preparation

### The Technology (Pillars)
Nine system pillars (from AGENT.md):

| Pillar | Status | Responsibility |
|--------|--------|-----------------|
| `governance_engine` | ✓ Complete | Entropy-based decision routing |
| `cryptographic_ledger` | ✓ Complete | Merkle-chained Ed25519 signatures |
| `formal_guard` | ✓ Complete | Pre-commit invariant enforcement |
| `sandbox_execution` | ✓ Complete | Isolated function execution |
| `benchmark_harness` | ✓ Complete | Performance tracking & regression testing |
| `provider_abstraction` | ✓ Complete | Multi-model vendor interface |
| `billing_infrastructure` | ✓ Complete | Stripe-integrated usage metering |
| `guardian_dashboard` | ✓ Complete | React SPA dashboard — AutoDemo, customer portal, owner portal |
| `esgf_sdk` | ✓ Complete (Phase 2 foundation) | @governed decorator + verification |

---

## THE 30-DAY PLAN (Historical Snapshot)

This section captures the original launch sequence. The dashboard, landing page, demo page, and Phase 2–4 technical work referenced elsewhere in this README are already shipped.

### Week 1: Launch & Traction
- **Sales:** Outreach sprint (20 messages), first calls, first contract ($2,500)
- **Engineering:** Test stabilization, landing/demo/dashboard polish
- **Goal:** Prove product-market fit signal

### Week 2: Delivery & Momentum
- **Sales:** Pilot #1 integration, Pilots #2-#3 calls, second contract
- **Engineering:** Dashboard and metrics live, gather early usage feedback
- **Goal:** Real customer data in system

### Week 3: Validation & Conversion
- **Sales:** Pilot feedback calls, negotiate SaaS conversions ($2,500/mo each)
- **Engineering:** Tier upgrade design and production hardening
- **Goal:** Recurring revenue starts

### Week 4: Scale & Phase 2
- **Sales:** Additional pilots, upsell to Professional tier (+$4,000/mo)
- **Engineering:** Phase 3/4 hardening follow-through and customer-driven iteration
- **Goal:** $10K-$24K revenue + Phase 2 progress

---

## ESSENTIAL DOCUMENTATION

| File | Purpose |
|------|---------|
| `AGENT.md` | Operational governance + phase gates (required reading) |
| `docs/SYSTEM_REALITY.md` | What's real vs simulation — honest system assessment |
| `docs/ARCHITECTURE_FIXES_SUMMARY.md` | 8 critical flaws fixed (4 on Mar 9, 4 more on Mar 16, 2026) |

---

## ARCHITECTURE & IMPLEMENTATION

**Core Governance Layer**
| File | Purpose |
|------|---------|
| governance/engine.py | Entropy-based decision routing, multi-policy synthesis, causal tracing |
| governance/ledger.py | Immutable cryptographic ledger (Ed25519 signing, Merkle chaining, thread-safe writes) |
| governance/sandbox.py | Formal guard - operation allowlist enforcement with parameter validation |
| governance/conflict.py | Policy conflict resolution using weighted pseudo-inverse synthesis |
| governance/priority_queue.py | SLA enforcement - tier-based queue (Enterprise <10ms, Professional <100ms) |

**Integration & Billing**
| File | Purpose |
|------|---------|
| esgf_schema.py | Pydantic data contracts (GovernanceDecision, SystemState, PolicyAction, etc.) |
| esgf_merged.py | Unified orchestration (engine initialization, tenant management, health checks) |
| esgf_billing.py | Stripe integration - tenant provisioning, metered usage, tier pricing ($2.5K/$6.5K/$18K) |
| esgf_compliance.py | Compliance report generation (EU AI Act Article 11 - decision statistics, audit export) |

**Customer API**
| File | Purpose |
|------|---------|
| governed_decorator.py | @governed decorator - function interception, decision enforcement, billing tracking |
| server.py | FastAPI endpoints (/audit/trace, /billing/provision, /dashboard/*, /auth/*, etc.) |
| esgf_sdk.py | Customer-facing SDK wrapper (verification, tracing) |

**Advanced Features (Optional)**
| File | Purpose |
|------|---------|
| chrono_engine.py | Temporal intelligence - time dilation simulation for testing (experimental) |
| chrono_governance_bridge.py | Integration bridge for temporal features |
| inference/base.py | Abstract provider interface for ML models |
| inference/neurofabric_provider.py, inference/bioswarm_provider.py | Test stubs (not for production) |

### Testing
**Total Tests:** 212 passing across 18 test files (March 17, 2026)

| Category | Count |
|----------|-------|
| Governance Engine | 26 |
| Ledger & Cryptography | 9 |
| Billing & Stripe | 22 |
| Priority Queue & SLA | 27 |
| @governed Decorator (incl. PolicyCache, CircuitBreaker, HMAC) | 23 |
| Phase 2 Gates | 11 |
| Enterprise Billing | 21 |
| Compliance Reporting | 21 |
| Dashboard & RBAC | 20 |
| Architecture Fixes | 16 |
| Load & Chaos Tests | 15 |
| Governance Scanner | 7 |
| Guardian API Client | 14 |

To run: `python3 -m pytest --tb=short -q`

---

## PHASE GATES (Progress Tracking)

### Phase 1 (Complete ✓)
- [✓] `/audit/trace` endpoint returns signed trace
- [✓] `verify_trace()` SDK verifies with public key
- [✓] Chaos test: 10K concurrent, 0% corruption, p99<100ms
- [✓] Stripe provisioning: customer + subscription
- [✓] Stripe Meter: usage events received
- [✓] Webhook handler: 4 event types verified
- [✓] Grace period + suspension: verified
- [✓] Regulatory alignment brief: complete
- [✓] All pytest: 212/212 passing

### Phase 2 (Complete ✓)
- [✓] Gate #1: Feature flags (Starter/Professional/Enterprise gating)
- [✓] Gate #2: `@governed` decorator (function interception)
- [✓] Gate #3: Tier upgrade flow (proration math)
- [✓] Gate #4: SDK seat billing (per-seat pricing)
- [✓] Gate #5: Dashboard gating (tier-based visibility)
- [✓] Gate #6: Billing integration (Stripe metering)

### Phase 3 (Complete ✓)

- [✓] Priority queue: sub-10ms Tier-1 validated (`test_priority_queue_sla_load.py`, p99 = 0.001ms)
- [✓] Error Boundary: GOVERNANCE_FAILURE / EXTERNAL_AGENT_FAILURE / SLA_FAILURE classified (`test_architecture_fixes.py`)
- [✓] Indemnification spec: legal review complete
- [✓] Enterprise Stripe provisioning: annual + month-to-month (`test_enterprise_billing.py`)
- [✓] Compliance report billed: one-time Stripe meter event on generation (`test_compliance_reporting.py`)
- [✓] All pytest harnesses: 212/212 passing

---

## CRITICAL PATH (What's Blocking What)

```
REVENUE TRACK (Sales)
├─ Outreach (Days 1-2) ✓ Ready
├─ First calls (Days 3-5) ✓ Ready
└─ First contract (Day 5) ✓ Ready

ENGINEERING TRACK (Phase 3 — 5/6 complete)
├─ All tests (Daily) ✓ 212/212 stable
├─ Guardian Dashboard ✓ SHIPPED (static/index.html — /app)
├─ PolicyCache + CircuitBreaker ✓ SHIPPED (Phase 4 early)
├─ HMAC decision signing ✓ SHIPPED (Phase 4 early)
├─ Governance scanner ✓ SHIPPED (Phase 4 early)
└─ Indemnification spec ← LAST BLOCKER (legal review — non-code)

DEPLOYMENT TRACK
├─ P0: Rotate Stripe test keys in .env (10 min, required before push)
├─ P1: Set live Stripe keys + OWNER_API_KEY in Railway env vars
└─ P2: Push to GitHub → Railway auto-deploys

BOTTLENECK: Indemnification spec (legal review required, non-code)
```

---

## DEPLOYMENT & TESTING

### Deploy to Production (30 minutes)
See START_HERE_LAUNCH.md for step-by-step guide.

Quick steps:
1. Push to GitHub: `git push origin main` (Railway auto-deploys)
2. Add Stripe live keys to Railway environment variables
3. Create CNAME DNS record pointing to Railway URL
4. Test: `curl https://api.yourdomain.com/api/v1/health`

### Run Tests Locally
```bash
python3 -m pytest --tb=short -q
```

### Run Performance Benchmarks
```bash
python3 bench_suite.py --baseline  # Create baseline
python3 bench_suite.py --compare   # Compare to baseline
```

### Start Local Server
```bash
python3 server.py
# Runs on http://localhost:8000
```

### Submit Test Trace
```bash
curl -X POST http://localhost:8000/api/v1/audit/trace \
  -H "Authorization: Bearer test-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "test",
    "input": [0.1, 0.2, 0.3],
    "output": 0.75,
    "confidence": 0.91
  }'
```

---

## SUCCESS CRITERIA (30 Days)

### Revenue ✓
- [ ] 20+ messages sent
- [ ] 8+ replies (40%+ response)
- [ ] 3+ calls completed
- [ ] 1-3 pilots signed ($2,500-$7,500)
- [ ] 1-3 SaaS conversions ($2,500-$7,500 MRR)

### Engineering ✓
- [✓] Phase 1 + Phase 2: 100% stable, 212/212 tests passing
- [✓] Guardian Dashboard: shipped (AutoDemo, customer portal, owner portal)
- [✓] Phase 4 early items: PolicyCache, CircuitBreaker, HMAC, scanner
- [ ] Live Railway deployment (set env vars, push)
- [ ] Real customer data flowing

### Product ✓
- [ ] @governed decorator in use by 3+ customers
- [ ] Compliance reports generated
- [✓] Dashboard showing real metrics (Guardian Dashboard at /app)
- [ ] Pilot feedback incorporated

---

## DECISION FRAMEWORK (From AGENT.md)

Every task must answer:
1. **Which pillar does this serve?**
2. **Which gate condition does this advance?**
3. **Will this ship with tests?**

If you can't answer all three: **do not build it**.

Examples:
- ✓ Guardian Dashboard → `guardian_dashboard` pillar → Gate #1 → Tests included
- ✓ Feature flags → `billing_infrastructure` pillar → Gate #6 → Tests included
- ✗ "Nice to have" documentation → No pillar → No gate → **Don't build**

---

## DOCUMENTATION FILES

**Only these 14 .md files should exist. Update them, don't create new ones.**

1. `README.md` — This file (overview, architecture, quick start)
2. `AGENT.md` — Operational doctrine & phase gates
3. `SYSTEM_REALITY.md` — What's real vs simulation (includes Critical Architectural Flaws section)
4. `CUSTOMER_GETTING_STARTED.md` — 30-minute integration guide + test suite appendix
5. `CUSTOMER_OPERATIONS_GUIDE.md` — Production deployment guide
6. `DEPLOY_TO_PRODUCTION.md` — Deployment options (Heroku/AWS/GCP)
7. `SALES_TEMPLATES.md` — Email & pitch templates
8. `LAUNCH_CHECKLIST_7_DAYS.md` — Day-by-day launch plan
9. `START_HERE_LAUNCH.md` — Launch entry point
10. `LAUNCH_COMPLETE.md` — Launch kit summary
11. `COMPREHENSIVE_SYSTEM_ANALYSIS_AND_VALUATION.md` — Market analysis & investor pitch
12. `ARCHITECTURE_FIXES_SUMMARY.md` — 8 critical flaw fixes (4 CRITICAL Mar 9, Flaws 5–8 and 12 Mar 16)
13. `docs/PROPOSED_ARCHITECTURAL_UPGRADES.md` — Phase 4–6 roadmap (Upgrades 1–3 SHIPPED, 4–5 Q2 2026, 6–8 Phase 5)
14. `.amp/amp.md` — Enforcement Codex (authoritative doctrine for all agents)

### Critical Fixes Quick Reference

| Audience | Read |
|----------|------|
| Engineers reviewing fixes | `docs/ARCHITECTURE_FIXES_SUMMARY.md` then `governed_decorator.py` then `test_architecture_fixes.py` |
| Regulators / compliance | `docs/SYSTEM_REALITY.md` (Critical Architectural Flaws section) |
| Phase 4–6 strategy | `docs/PROPOSED_ARCHITECTURAL_UPGRADES.md` |

See AGENT.md "FILE GOVERNANCE" section for rules.

---

## GETTING HELP

### Blocked on Sales?
- Read: `SALES_TEMPLATES.md` — outreach and pitch templates
- Do: Send 5 messages + monitor replies
- Fallback: Offer $1,500 pilot instead of $2,500

### Blocked on Engineering?
- Read: `SYSTEM_REALITY.md` (risks section)
- Do: Run tests + identify failure root cause
- Fallback: Simplify scope (MVP first, polish later)

### Blocked on Tests?
- Check: governance/ledger.py _flush_buffer() called after append()
- Check: File paths are correct (test_*.jsonl in current directory)
- Check: Ed25519 key generated (test_*_key.pem exists)

---

## WHAT THIS SYSTEM DOES

**Production-Ready Components (100% Real)**
✓ Cryptographic ledger with Ed25519 signing + Merkle chaining (10K concurrent ops, 0% corruption)
✓ Policy enforcement with entropy-based adaptive gating (FAST/MID/FULL paths)
✓ Tier-based priority queue with SLA enforcement (Enterprise <10ms p99)
✓ Stripe integration - customer provisioning, metered usage, billing ($2.5K/$6.5K/$18K/mo)
✓ @governed decorator - function interception, decision enforcement, metrics tracking
✓ Sandbox formal guard - operation allowlist with parameter validation
✓ Compliance reporting - EU AI Act Article 11 (decision stats, audit export, JSON/CSV/PDF)

**What You Provide**
- Your ML models (wrapped with @governed decorator)
- Your compliance rules (policy thresholds, fairness definitions)
- Your approval workflows (if human review gates are used)

**Result:** Enterprise compliance automation - audit time from 8 weeks to 2 weeks, cost from $200K to $2.5K-$18K/year

**30-Day Revenue Goal**
- $2.5K-$10K (design partner pilots)
- $6.5K-$18K MRR starting month 2 (SaaS conversions)

---

## NEXT STEPS

**Immediate (Today):**
1. Read `AGENT.md` (10 min) — Understand operational doctrine
2. Run `python3 -m pytest --tb=short -q` (5 min) — Verify 212/212 pass
3. Rotate Stripe test keys + JWT secret in `.env` (10 min) — **P0: required before git push**
4. Choose your track: Engineer, Product, or Sales

**This Week:**
- Engineers: Set Railway live env vars, smoke-test deployed endpoint
- Sales: Execute 20-message outreach sprint (`SALES_TEMPLATES.md`)
- Legal: Draft indemnification spec (last Phase 3 gate condition)

**Success Metrics:**
- All tests passing ✓ (212/212)
- First design partner conversation completed
- Stripe live keys in Railway + health endpoint responding

---

## RESOURCES

- Stripe Dashboard: https://dashboard.stripe.com (test mode)
- Calendly: https://calendly.com (free tier)
- Carrd.co: https://carrd.co ($99/year landing page)
- GitHub Pages: https://pages.github.com (free hosting)
- Ed25519 reference: https://en.wikipedia.org/wiki/EdDSA
- EU AI Act: https://www.europarl.europa.eu/news/en/headlines/society/20230601STO93804/

---

## METRICS TO TRACK DAILY

Track this in a spreadsheet or Slack:

| Metric | Today | Week | Month |
|--------|-------|------|-------|
| Outreach messages sent | ? | 20 | 20+ |
| Replies | ? | 8 | 8+ |
| Calls scheduled | ? | 3 | 10+ |
| Pilots signed | ? | 1 | 3+ |
| Revenue (MTD) | $0 | $2.5K | $10K-$24K |
| MRR (recurring) | $0 | $0 | $2.5K-$11.5K |
| All tests | 212/212 | 212/212 | 212/212 |
| Guardian Dashboard % | 100% (shipped) | 100% (shipped) | 100% (shipped) |

---

## THE CONVICTION (From Founder)

> You're not asking people to buy a dream.  
> You're asking them to pay $2,500 to test a solution to a real, expensive, immediate problem.  
> That's the difference between a feature demo and a customer.

By Day 5: $2,500 in bank + proof of concept  
By Day 30: $10K-$24K revenue + Phase 2 started  
By Month 3: Recurring customers + Phase 2 complete  
By Month 12: $34K ARR + defensible business  

---

**Status: Ready to execute.**  
**Timeline: 30 days to revenue + Phase 2 progress.**  
**As of: March 16, 2026.**
**Next milestone: First pilot customer + live Railway deployment.**

---

*Last updated: March 19, 2026*
*This is your roadmap. Execute it.*


--------------------
