felipeofdev-ai · felipeofdev-ai · Feb 15, 2026 · Feb 15, 2026
diff --git a/.github/workflows/sdk-release.yml b/.github/workflows/sdk-release.yml
@@ -0,0 +1,26 @@
+name: SDK Release Preparation
+
+on:
+  workflow_dispatch:
+
+jobs:
+  package-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Build python sdk package
+        run: |
+          pip install build
+          cd sdk/python
+          python -m build
+      - name: Validate js package metadata
+        run: |
+          cd sdk/js
+          node -e "const p=require('./package.json'); if(!p.name) process.exit(1);"
+      - name: Validate rust crate metadata
+        run: |
+          cd sdk/rust
+          grep '^name = ' Cargo.toml
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.7.4
+    hooks:
+      - id: ruff
+        args: [--fix]
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,24 @@
 # Changelog
 
-All notable changes to BridgeTrace AI will be documented in this file.
+All notable changes to BridgeTrace AI are documented in this file.
+
+The format follows Keep a Changelog and Semantic Versioning.
+
+## [Unreleased]
+
+### Added
+- Enterprise credibility docs: `SECURITY.md`, `SLA.md`, `VERSIONING.md`, `THREAT_MODEL.md`.
+- Compliance readiness and architecture artifacts: `docs/COMPLIANCE_READINESS.md`, `SYSTEM_DESIGN.md`, `SCALING_STRATEGY.md`, `FAILURE_SCENARIOS.md`.
+- Business metrics endpoint `GET /metrics/business` and audit endpoint `GET /audit/logs`.
+- Tenant-aware quota controls and audit logging primitives.
+
+### Changed
+- Main middleware now supports tenant headers, optional auth enforcement, and enterprise audit trails.
+- Security module now supports API key validation and bearer-token based request authentication.
+
+### Documentation
+- Added `docs/PERFORMANCE_PROOF.md` with engine comparison matrix.
+- Added `docs/DISTRIBUTION_ROADMAP.md` for adoption strategy.
 
 ## [2.0.0] - 2026-02-08
 

diff --git a/FAILURE_SCENARIOS.md b/FAILURE_SCENARIOS.md
@@ -0,0 +1,17 @@
+# Failure Scenarios
+
+## Scenario 1: Traffic Spike / DoS-like burst
+- symptom: elevated 429, latency spikes
+- response: enforce stricter quota/rate limits, autoscale API
+
+## Scenario 2: Graph backend latency regression
+- symptom: trace p95 exceeds SLO
+- response: degrade to cached responses, trigger incident policy
+
+## Scenario 3: Cross-tenant data risk
+- symptom: incorrect tenant headers or mixed audit entries
+- response: block suspect requests, run audit replay, rotate keys
+
+## Scenario 4: Key compromise
+- symptom: unusual authenticated traffic
+- response: revoke/rotate API keys, force JWT invalidation
diff --git a/README.md b/README.md
@@ -7,6 +7,9 @@
 ![Docker](https://img.shields.io/badge/Docker-Ready-blue?style=for-the-badge&logo=docker)
 ![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)
 ![CI](https://img.shields.io/github/workflow/status/felipeofdev-ai/BridgeTrace-AI/CI?style=for-the-badge)
+![Benchmark Reproducible](https://img.shields.io/badge/Benchmark-Reproducible-success?style=for-the-badge)
+![Deterministic Engine](https://img.shields.io/badge/Deterministic%20Engine-Yes-success?style=for-the-badge)
+![External Validation](https://img.shields.io/badge/External%20Validation-Pending-orange?style=for-the-badge)
 
 **Enterprise-Grade Financial Traceability Engine**
 
@@ -20,6 +23,13 @@ Unified platform for tracing financial flows across banking systems (PIX), block
 
 ## ✨ Features
 
+## 🎯 Why BridgeTrace-AI
+
+**BridgeTrace-AI combines graph-native risk propagation with explainable outputs so compliance teams can act in minutes, not days.**
+
+---
+
+
 ### Core Capabilities
 - 🔗 **Unified Graph Model** - Banking + PIX + Crypto in one graph
 - 🔍 **Multi-Hop Tracing** - Follow money through complex transaction paths
@@ -85,16 +95,120 @@ alembic upgrade head
 uvicorn app.main:app --reload
 ```
 
+### Generate Demo Data
+```bash
+python scripts/generate_synthetic_data.py --count 1000
+python examples/scripts/basic_trace.py
+```
+
+
+### Generate Public Dataset v1
+```bash
+python scripts/generate_public_dataset_v1.py --rows 500 --seed 42
+```
+
 ### Access Services
 - **API**: http://localhost:8000
 - **API Docs**: http://localhost:8000/api/v2/docs
 - **Grafana**: http://localhost:3000 (admin/admin)
 - **Prometheus**: http://localhost:9090
+- **Dashboard Demo**: http://localhost:8000/dashboard
+- **Business Metrics**: http://localhost:8000/metrics/business
+- **Hosted Playground**: http://localhost:8000/playground
+
+---
+
+
+## ⚡ 5-Minute Integration
+
+```bash
+# 1) Start API
+uvicorn app.main:app --reload
+
+# 2) Health check
+curl http://localhost:8000/api/v2/health
+
+# 3) Functional trace call
+curl -X POST http://localhost:8000/api/v2/trace \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: dev-key-1" \
+  -H "X-Tenant-ID: demo" \
+  -d '{"source_id":"bank_001","max_hops":5,"min_amount":0}'
+
+# 4) Risk by entity
+curl "http://localhost:8000/api/v2/risk/entity_001?days=30" \
+  -H "X-API-Key: dev-key-1" \
+  -H "X-Tenant-ID: demo"
+```
+
+Python SDK minimal example:
+```python
+from bridge_trace_sdk import BridgeTraceSDK
+
+sdk = BridgeTraceSDK("http://localhost:8000", api_key="dev-key-1", tenant_id="demo")
+print(sdk.trace("bank_001"))
+print(sdk.risk("entity_001"))
+```
+
+CLI example:
+```bash
+python scripts/bt_cli.py --base-url http://localhost:8000 --api-key dev-key-1 --tenant demo trace --source bank_001
+python scripts/bt_cli.py --base-url http://localhost:8000 --api-key dev-key-1 --tenant demo risk --entity entity_001
+```
+
+---
+
+## 🔬 External Reproducibility Proof
+
+Run the exact public proof pipeline (dataset + benchmark + checksums):
+
+```bash
+./scripts/run_external_proof.sh
+```
+
+This generates reproducible artifacts and SHA256 fingerprints under `artifacts/`.
+
+---
+
+## 🌐 Hosted Playground (Public Mode)
+
+Open instantly in browser:
+
+- `GET /playground`
+- `GET /api/v2/playground/ping`
+- `GET /api/v2/playground/sample-trace`
+- `GET /api/v2/playground/sample-risk`
+- `GET /api/v2/demo/replay`
 
 ---
 
 ## 📖 Documentation
 
+- [Fortune 500 Tier-1 Enhancements Roadmap](docs/FORTUNE500_TIER1_ENHANCEMENTS.md)
+- [Development Guide](docs/DEVELOPMENT.md)
+- [Deployment Guide](docs/DEPLOYMENT.md)
+- [Installation Guide](docs/INSTALLATION.md)
+- [API Reference](docs/API_REFERENCE.md)
+- [Architecture Decisions](docs/ARCHITECTURE.md)
+- [Algorithm Spec](docs/ALGORITHM.md)
+- [BridgeTrace Technical Paper v1](docs/papers/BRIDGETRACE_TECHNICAL_PAPER_V1.md)
+- [BridgeTrace Synthetic Dataset v1](docs/datasets/BRIDGETRACE_SYNTHETIC_DATASET_V1.md)
+- [Security Policy](SECURITY.md)
+- [SLA](SLA.md)
+- [Versioning Policy](VERSIONING.md)
+- [Threat Model](THREAT_MODEL.md)
+- [Compliance Readiness](docs/COMPLIANCE_READINESS.md)
+- [System Design](SYSTEM_DESIGN.md)
+- [Scaling Strategy](SCALING_STRATEGY.md)
+- [Failure Scenarios](FAILURE_SCENARIOS.md)
+- [Performance Proof](docs/PERFORMANCE_PROOF.md)
+- [Distribution Roadmap](docs/DISTRIBUTION_ROADMAP.md)
+- [5-Minute Quickstart](docs/QUICKSTART_5MIN.md)
+- [SDK Publishing Plan](docs/SDK_PUBLISHING.md)
+- [Formal Whitepaper v1.0.0](docs/papers/WHITEPAPER_FORMAL_V1_0.md)
+- [Scientific Changelog](docs/papers/SCIENTIFIC_CHANGELOG.md)
+- [Official Competitive Comparison](docs/COMPETITIVE_COMPARISON.md)
+
 ### API Endpoints
 
 #### Health Checks
@@ -127,6 +241,15 @@ Content-Type: application/json
 }
 ```
 
+#### Professional API (Tier-1)
+```http
+POST /api/v2/trace
+GET /api/v2/risk/{entity_id}
+GET /api/v2/risk/propagation-map/{entity_id}
+GET /api/v2/graph/{entity_id}
+POST /api/v2/simulate
+```
+
 #### AI Explanations
 ```http
 POST /api/v2/ai/explain

diff --git a/SCALING_STRATEGY.md b/SCALING_STRATEGY.md
@@ -0,0 +1,17 @@
+# Scaling Strategy
+
+## Horizontal API Scaling
+- stateless API workers
+- externalize quota/audit stores (Redis/Postgres)
+
+## Compute Scaling
+- offload heavy simulations to worker queue
+- batch risk recomputation by tenant
+
+## Graph Scaling
+- in-memory for dev
+- migrate to Neo4j/TigerGraph backend for production
+
+## Observability Scaling
+- Prometheus scraping + remote write
+- business KPIs streamed to warehouse
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,29 @@
+# Security Policy
+
+## Supported Versions
+- `2.x` receives active security updates.
+
+## Reporting a Vulnerability
+Please report vulnerabilities privately to: `security@bridgetrace.ai`.
+
+Include:
+- affected component and version
+- proof of concept or reproduction steps
+- impact assessment (CIA)
+
+We follow coordinated disclosure:
+- acknowledgement in 48h
+- triage in 5 business days
+- remediation timeline based on severity (Critical: 72h target)
+
+## Security Controls (Current)
+- JWT and API key authentication support
+- Request ID propagation and audit logs
+- Tenant quotas and rate limiting baseline
+- Structured logging and metrics endpoints
+
+## Hardening Roadmap
+- key rotation automation
+- secret manager integration
+- distributed rate limiting
+- mTLS for service-to-service communication
diff --git a/SLA.md b/SLA.md
@@ -0,0 +1,17 @@
+# Service Level Agreement (SLA)
+
+## Availability Targets
+- API availability: **99.9%** monthly
+- Critical endpoints (`/api/v2/trace`, `/api/v2/risk/*`): **99.95%** objective (enterprise tier)
+
+## Performance Targets
+- `POST /api/v2/trace`: p95 < 1.5s
+- `GET /api/v2/risk/{entity}`: p95 < 800ms
+- `GET /metrics/business`: p95 < 300ms
+
+## Support Windows
+- P1 incidents: 24/7 response, first response within 30 minutes
+- P2 incidents: business hours, first response within 4 hours
+
+## Exclusions
+Planned maintenance windows and upstream cloud outages are excluded and communicated in advance.
diff --git a/SYSTEM_DESIGN.md b/SYSTEM_DESIGN.md
@@ -0,0 +1,15 @@
+# System Design
+
+BridgeTrace-AI is structured as:
+- FastAPI API layer
+- service layer for trace/risk/simulation
+- analytics engine for risk propagation
+- pluggable graph backend abstraction
+- observability + business metrics
+
+Data flow:
+1. request enters middleware (request-id/auth/quota/audit)
+2. routed to service method
+3. graph traversal/propagation executed
+4. metrics and audit entries emitted
+5. response returned with tenant/request headers
diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md
@@ -0,0 +1,30 @@
+# Threat Model
+
+## Assets
+- financial transaction metadata
+- risk scores and propagation maps
+- tenant usage/audit logs
+
+## Trust Boundaries
+- external client -> API gateway
+- API -> graph engine / storage
+- API -> monitoring / logging
+
+## Main Threats (STRIDE)
+- **Spoofing**: stolen API keys/JWT
+- **Tampering**: request payload manipulation
+- **Repudiation**: missing or forged audit trail
+- **Information Disclosure**: tenant data leakage
+- **Denial of Service**: request floods or expensive graph traversals
+- **Elevation of Privilege**: cross-tenant access via weak isolation
+
+## Mitigations (Current)
+- request ID + audit logs
+- baseline auth support (JWT/API key)
+- quota controls per tenant and global rate limiting
+- structured logging and observability
+
+## Priority Mitigations (Next)
+- enforced auth in production profiles
+- distributed quotas and WAF
+- data encryption at rest and in transit hardening
diff --git a/VERSIONING.md b/VERSIONING.md
@@ -0,0 +1,18 @@
+# Versioning Policy
+
+BridgeTrace-AI follows **Semantic Versioning 2.0.0**.
+
+## Format
+`MAJOR.MINOR.PATCH`
+
+- **MAJOR**: incompatible API or behavior changes
+- **MINOR**: backward-compatible features
+- **PATCH**: backward-compatible bug fixes
+
+## API Compatibility
+- API version prefix (`/api/v2`) is stable for all `2.x` releases.
+- Breaking API changes require a new prefix (`/api/v3`).
+
+## Deprecation Policy
+- Deprecated endpoints are announced in `CHANGELOG.md`.
+- Minimum deprecation window: 2 minor releases.
diff --git a/app/analytics/__init__.py b/app/analytics/__init__.py
@@ -0,0 +1,5 @@
+"""Analytics modules for advanced risk intelligence."""
+
+from app.analytics.risk_propagation import RiskPropagationEngine, PropagationResult
+
+__all__ = ["RiskPropagationEngine", "PropagationResult"]