admina-framework 0.9.0__py3-none-any.whl

admina_framework-0.9.0.dist-info/METADATA

@@ -0,0 +1,575 @@
+Metadata-Version: 2.4
+Name: admina-framework
+Version: 0.9.0
+Summary: Admina — governed AI development framework
+Author-email: Stefano Noferi <info@admina.org>
+Maintainer-email: Stefano Noferi <info@admina.org>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://admina.org
+Project-URL: Repository, https://github.com/admina-org/admina
+Project-URL: Documentation, https://github.com/admina-org/admina#readme
+Project-URL: Issues, https://github.com/admina-org/admina/issues
+Project-URL: Changelog, https://github.com/admina-org/admina/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/admina-org/admina/blob/main/SECURITY.md
+Keywords: ai,governance,compliance,eu-ai-act,pii,llm,mcp,proxy,agent-security,injection-firewall,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: click<9,>=8.1
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: cryptography<48,>=41.0
+Provides-Extra: proxy
+Requires-Dist: fastapi<1,>=0.104; extra == "proxy"
+Requires-Dist: uvicorn[standard]<1,>=0.24; extra == "proxy"
+Requires-Dist: httpx<1,>=0.25; extra == "proxy"
+Requires-Dist: pydantic<3,>=2.5; extra == "proxy"
+Requires-Dist: pydantic-settings<3,>=2.3; extra == "proxy"
+Requires-Dist: python-dotenv<2,>=1.0; extra == "proxy"
+Requires-Dist: redis<6,>=5.0; extra == "proxy"
+Requires-Dist: boto3<2,>=1.34; extra == "proxy"
+Requires-Dist: minio<8,>=7.2; extra == "proxy"
+Requires-Dist: clickhouse-connect<1,>=0.7; extra == "proxy"
+Requires-Dist: typer<1,>=0.9; extra == "proxy"
+Provides-Extra: nlp
+Requires-Dist: spacy<4,>=3.8; extra == "nlp"
+Requires-Dist: scikit-learn<2,>=1.3; extra == "nlp"
+Requires-Dist: numpy<2,>=1.24; extra == "nlp"
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api<2,>=1.20; extra == "telemetry"
+Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "telemetry"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.20; extra == "telemetry"
+Requires-Dist: opentelemetry-instrumentation-fastapi<1,>=0.40b0; extra == "telemetry"
+Provides-Extra: full
+Requires-Dist: admina-framework[nlp,proxy,telemetry]; extra == "full"
+Dynamic: license-file
+
+# Admina — Governed AI Development Framework
+
+**Install once, get governed AI. The open framework for building AI applications that are governed by design.**
+
+Admina gives you an SDK, a transparent proxy, a plugin system, a CLI, and a dashboard — all in one install. Every AI interaction is governed: PII redacted, injections blocked, loops broken, actions audited, EU AI Act compliance tracked. Works in-process (SDK) and over the network (proxy). Zero code changes to add governance to existing applications.
+
+> ⚖️ **Compliance disclaimer.** Admina is a self-assessment and
+> defense-in-depth tool. The EU AI Act gap-analysis and risk
+> classification features are **decision-support aids, not legal
+> advice**. They do not replace the conformity assessment required
+> under EU AI Act Art. 43 for high-risk systems, nor the involvement
+> of a notified body where the regulation requires one.
+>
+> **EU AI Act timeline (after the Omnibus VII agreement of 7 May 2026):**
+> Art. 5 prohibitions in force since 2 February 2025; GPAI obligations
+> in force since 2 August 2025; Art. 50 transparency for synthetic
+> content and the new NCII / synthetic-CSAM prohibition apply from
+> 2 December 2026; **Annex III high-risk obligations from 2 December
+> 2027** (postponed from 2 Aug 2026); Annex I high-risk from 2 August
+> 2028 (postponed from 2 Aug 2027). The full machine-readable timeline
+> ships with Admina as `admina.domains.compliance.eu_ai_act.EU_AI_ACT_DEADLINES`.
+> See [`MODEL_CARD.md`](MODEL_CARD.md) for the full scope, limitations,
+> and known failure modes of every Admina component.
+
+[![PyPI version](https://img.shields.io/pypi/v/admina-framework.svg)](https://pypi.org/project/admina-framework/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/admina-framework.svg)](https://pypi.org/project/admina-framework/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.11+-green.svg)](https://python.org)
+[![Rust](https://img.shields.io/badge/Rust-Engine-orange.svg)](core-rust/)
+[![CI](https://github.com/admina-org/admina/actions/workflows/ci.yml/badge.svg)](https://github.com/admina-org/admina/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-admina.org-blue.svg)](https://admina.org/docs)
+[![Version](https://img.shields.io/badge/version-0.9.0-blue.svg)](CHANGELOG.md)
+[![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20macOS-lightgrey.svg)](CONTRIBUTING.md#supported-platforms)
+
+```python
+from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
+from admina.plugins.builtin.adapters.ollama import OllamaAdapter
+from admina.plugins.builtin.connectors.chromadb import ChromaDBConnector
+
+# Every call is governed: PII redacted, injections blocked, audited
+adapter = OllamaAdapter(host="http://localhost:11434")
+model = GovernedModel(model_name="llama3.1:8b", adapter=adapter)
+response = await model.ask("Summarize this document")
+
+# Data governance: residency enforcement, PII classification
+connector = ChromaDBConnector(host="localhost", port=8000)
+data = GovernedData(connector=connector, residency_zone="eu")
+await data.ingest(documents)
+
+# Agent governance: validate every tool call before execution
+async def my_upstream(method, params, **kw): ...  # your MCP/HTTP client
+agent = GovernedAgent(upstream=my_upstream)
+result = await agent.call("tools/call", {"name": "read_file", "arguments": {}})
+
+# Compliance: EU AI Act gap analysis and risk classification
+kit = ComplianceKit()
+report = kit.gap_analysis(risk_category="high", current_compliance={...})
+```
+
+## Quick Start
+
+### Install from PyPI
+
+```bash
+# SDK only (lightweight, pure Python)
+pip install admina-framework
+
+# Proxy + infrastructure deps
+pip install "admina-framework[proxy]"
+
+# Everything (proxy + NLP + telemetry)
+pip install "admina-framework[full]"
+
+# After [nlp] / [full] install: download the spaCy NER model
+python -m spacy download en_core_web_sm
+
+# Optional: Rust-accelerated engine (auto-detected at runtime)
+pip install admina-core
+```
+
+> The PyPI distribution name is `admina-framework`; the Python import
+> name is `admina` (e.g. `from admina import GovernedModel`). This is
+> a normal Python pattern — same as `python-dateutil` → `import dateutil`.
+
+> The Rust engine is an optional accelerator. `pip install admina-framework`
+> ships only the pure-Python implementation; Admina auto-detects the
+> Rust engine at runtime and falls back to the Python implementation
+> if it's not installed.
+
+### Or install from source
+
+```bash
+git clone https://github.com/admina-org/admina.git
+cd admina
+
+# Option 1: SDK only (lightweight)
+pip install -e .
+python -c "from admina import GovernedModel; print('SDK ready')"
+
+# Note: To use the OllamaAdapter, install Ollama (https://ollama.ai)
+# and pull a model first: ollama pull llama3.1:8b
+
+# Option 2: Proxy + infra deps
+pip install -e ".[proxy]"
+
+# Option 3: Everything (proxy + NLP + telemetry)
+pip install -e ".[full]"
+
+# Option 4: Full stack (proxy + dashboard + infra via Docker)
+./scripts/bootstrap-secrets.sh   # Auto-generate .env with random credentials
+docker compose up --build        # Credentials printed at bootstrap
+
+# Option 5: CLI
+pip install -e .
+admina init my-project   # Scaffold a governed AI project
+cd my-project            # admina dev runs from the project directory
+admina dev               # Start local dev stack
+```
+
+Dashboard: [http://localhost:3000](http://localhost:3000) | API docs: [http://localhost:8080/docs](http://localhost:8080/docs)
+
+## Architecture
+
+Admina is organized into 4 governance domains:
+
+| Domain | What it governs | Key features |
+|--------|----------------|--------------|
+| **Data Sovereignty** | Where data lives and how it's protected | PII redaction (spaCy + regex), residency zones, data classification |
+| **AI Infrastructure** | LLM and RAG stack | Ollama backend, ChromaDB vectors, Open WebUI, GPU auto-detect |
+| **Agent Security** | What agents can do | Injection firewall (Rust), loop breaker, proxy governance |
+| **Compliance** | Regulatory obligations | EU AI Act (Art. 6-15), forensic black box (SHA-256 chain), OTEL |
+
+Every governance feature works in **dual mode** — both via SDK (in-process) and proxy (network):
+
+```
+SDK Mode:                           Proxy Mode:
+  your code                           AI Agent
+    |                                   |
+  GovernedModel.ask()               POST /mcp
+    |                                   |
+  [governance pipeline]             [governance pipeline]
+    |                                   |
+  Ollama / OpenAI                   MCP Server / LLM
+```
+
+## The 4 Governance Domains
+
+| Domain | Capabilities | Engine |
+|--------|-------------|--------|
+| **Agent Security** | Anti-injection firewall (15 regex + heuristic scoring), loop breaker (TF-IDF cosine similarity) | Rust + Python |
+| **Data Sovereignty** | PII redaction (email, SSN, credit cards, IBAN, phone, IP), residency enforcement, data classification | Rust + spaCy NER |
+| **Compliance** | EU AI Act risk classification (Art. 6) and gap analysis (Art. 9-15), forensic black box (SHA-256 hash chain), OTEL native spans | Rust + Python |
+| **AI Infrastructure** | LLM engine (Ollama, OpenAI), RAG pipeline (ChromaDB), Open WebUI | Python |
+
+All governance domains operate **bidirectionally** — scanning both outbound requests and inbound responses.
+
+## SDK
+
+Four governed primitives, each with async + sync interfaces:
+
+```python
+from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
+```
+
+| Primitive | Purpose | Governance applied |
+|-----------|---------|-------------------|
+| `GovernedModel` | LLM calls (Ollama, OpenAI) | PII redaction on prompts and responses, event audit |
+| `GovernedData` | Data ingestion and queries | PII classification, residency enforcement, access audit |
+| `GovernedAgent` | MCP/A2A agent calls | Firewall, PII, loop breaker — full proxy pipeline in-process |
+| `ComplianceKit` | Regulatory compliance | EU AI Act risk classification, gap analysis, report generation |
+
+## Plugin System
+
+9 plugin interfaces, auto-discovered from `plugins/builtin/` or installed via CLI:
+
+| Interface | Builtin implementations |
+|-----------|------------------------|
+| Model Adapter | Ollama, OpenAI |
+| Data Connector | ChromaDB, Filesystem |
+| Governance Domain | GuardrailsAI (toxic, jailbreak, bias, PII) |
+| Compliance Template | EU AI Act |
+| Transport Adapter | MCP, HTTP REST |
+| Forensic Store | Filesystem, S3-compatible (boto3), MinIO (legacy) |
+| Auth Provider | API Key |
+| PII Engine | spaCy + Regex |
+| Alert Channel | Log, Webhook |
+
+```bash
+admina plugin list                    # List registered plugins
+admina plugin install ./my-plugin     # Install a custom plugin
+admina plugin create my-domain        # Scaffold a new plugin
+```
+
+## CLI
+
+```bash
+admina init my-project     # Scaffold project with admina.yaml + docker-compose.yml
+admina dev                 # Local mode: proxy + dashboard on :3000 (no Docker)
+admina dev --stack         # Docker stack: + redis + clickhouse + minio + grafana
+admina dev --with-llm      # --stack + ollama + chromadb + open-webui
+admina plugin list         # List all registered plugins
+admina plugin install X    # Install a plugin from path or registry
+admina plugin create X     # Scaffold a new plugin from template
+```
+
+`admina dev` defaults to a **single-process local mode** with zero Docker
+dependency: one uvicorn serves the proxy API and the dashboard SPA on the
+same port. Use `--stack` for the production-like Docker compose, or
+`--with-llm` to also boot local LLM services.
+
+## Forensic backend — choose deliberately
+
+The forensic blackbox (the SHA-256 hash chain that makes the audit trail
+tamper-evident) supports four backends. Read this before picking one for
+production.
+
+| Backend | License | When to use | Caveats |
+|---------|---------|-------------|---------|
+| **`memory`** *(default)* | n/a | Local development, tests, demos | Records are LOST on restart — no audit persistence. Loud warning at startup. |
+| **`filesystem`** | n/a | Single-host on-prem, air-gapped, smaller deployments | Persistence depends on the host filesystem; not ideal for HA. Requires `FORENSIC_BASE_DIR`. |
+| **`s3`** *(boto3)* | Apache 2.0 (boto3) | Production / HA / multi-region | Works with **any S3-compatible service** — AWS S3, Cloudflare R2, Backblaze B2, **SeaweedFS** (Apache 2.0), **Garage** (AGPLv3), **Ceph RGW** (LGPLv2). Recommended new default. |
+| **`minio`** *(legacy)* | see below ⚠️ | Backwards compatibility with existing MinIO clusters | Two distinct concerns; read the disclaimer. |
+
+> ⚠️ **MinIO disclaimer — what users of Admina need to know.**
+>
+> MinIO has two separate licensing/maintenance issues that can affect
+> downstream users of Admina, even though Admina itself is Apache 2.0:
+>
+> 1. **MinIO Server is AGPLv3.** If you deploy MinIO Server as part of a
+>    network-accessible service (e.g. a SaaS that exposes Admina's
+>    dashboard or API to the public Internet), AGPLv3's network clause
+>    can be read to require you to publish the source code of the
+>    *combined* application that interacts with MinIO over the network.
+>    The MinIO commercial license removes this obligation, but is paid.
+>    This is **not** an Admina obligation — Apache 2.0 is permissive —
+>    but it is an obligation MinIO Server itself imposes on whoever
+>    runs it.
+> 2. **The MinIO Python SDK has been archived.** No more security
+>    patches, no support for new Python releases. Continuing to depend
+>    on it is a supply-chain risk.
+>
+> **Recommendation:** for new deployments, use `FORENSIC_BACKEND=s3`.
+> The `boto3` client is Apache 2.0 and works against any S3-compatible
+> service. Two open-source FOSS-friendly options that don't trigger the
+> AGPL network clause for typical Admina deployments:
+> - **SeaweedFS** (Apache 2.0, S3 gateway, lightweight, single binary)
+> - **Garage** (AGPLv3, but as a backend — Garage's AGPL applies to
+>   Garage itself, not to applications that connect to it via S3 API)
+>
+> Existing MinIO deployments keep working through `FORENSIC_BACKEND=minio`,
+> but plan a migration. The `minio` backend will be removed in a future
+> release.
+
+## Dashboard
+
+Real-time governance dashboard on port 3000:
+
+- **Governance Score** — 0-100 composite metric (data residency, audit coverage, attack rate, forensic integrity, EU AI Act compliance)
+- **Live Feed** — streaming governance events via WebSocket
+- **Compliance Gaps** — EU AI Act gap analysis with article-level detail
+- **Infrastructure Health** — proxy, Redis, MinIO, ClickHouse, OTEL status
+
+API backend: `GET /api/dashboard/score`, `/feed`, `/compliance`, `/sovereignty`, `/infra`, `/models`
+
+## Configuration
+
+Admina uses `admina.yaml` as the primary config file (with `.env` fallback for backward compatibility):
+
+```bash
+cp admina.yaml.example admina.yaml   # Copy and customize
+```
+
+See [`admina.yaml.example`](admina.yaml.example) for all options including domains, AI infra, plugins, dashboard, forensic storage, alert channels, and integrations.
+
+### Environment variables (Docker / .env)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ADMINA_API_KEY` | *(empty)* | API key for all endpoints |
+| `UPSTREAM_MCP_URL` | `http://localhost:9000` | Default upstream MCP server |
+| `REDIS_URL` | `redis://localhost:6379/0` | Session state + rate limiting |
+| `MINIO_SECRET_KEY` | *(required)* | MinIO secret key for forensic storage |
+| `LOG_LEVEL` | `INFO` | Logging verbosity |
+
+## Integrations
+
+### GuardrailsAI
+
+ML-based content validation (toxic language, jailbreak, bias, PII via Presidio) as a governance domain plugin:
+
+```bash
+# Upstream guardrails-ai is currently in PyPI quarantine. Install it
+# manually from your local mirror or wheel cache; once available, the
+# plugin in admina/plugins/builtin/guards/guardrailsai_guard.py will
+# detect it automatically.
+pip install <your-guardrails-ai-wheel>
+```
+
+Enable in `admina.yaml` under `agent_security.domains.guardrailsai`. All inference runs locally by default — no data leaves the deployment perimeter.
+
+### OpenClaw
+
+Govern OpenClaw agent actions through the Admina proxy. Every tool call, shell command, and API request is validated before execution:
+
+```bash
+cd integrations/openclaw/admina-governance
+chmod +x setup.sh && ./setup.sh
+```
+
+The skill uses `POST /api/v1/validate` (pre-action) and `POST /api/v1/audit` (post-action) endpoints.
+
+### n8n
+
+Community nodes for n8n workflow automation:
+
+| Node | Purpose |
+|------|---------|
+| **Admina Govern** | Inline governance check — validates workflow data, blocks injections, redacts PII |
+| **Admina Audit** | Logs workflow events to forensic black box with EU AI Act risk classification |
+| **Admina Dashboard** | Trigger node — fires on governance events via WebSocket |
+
+Install: `npm install n8n-nodes-admina` in your n8n instance.
+
+### Cheshire Cat AI
+
+Govern all Cheshire Cat interactions via three Python hooks (`agent_fast_reply`, `before_cat_sends_message`, `before_cat_recalls_memories`):
+
+```bash
+cd integrations/cheshirecat/admina-plugin
+./setup.sh    # Start Admina sidecar
+# Copy plugin into Cheshire Cat plugins/ directory
+```
+
+### LangChain
+
+Drop-in callback handler — governs every LLM call and tool invocation in-process:
+
+```python
+from admina.integrations.langchain.callbacks import AdminaCallbackHandler
+
+handler = AdminaCallbackHandler()
+llm = ChatOpenAI(callbacks=[handler])
+```
+
+### CrewAI
+
+Step and task callbacks for multi-agent governance:
+
+```python
+from admina.integrations.crewai.callbacks import admina_step_callback, admina_task_callback
+
+agent = Agent(role="Researcher", step_callback=admina_step_callback)
+crew = Crew(agents=[agent], tasks=[task], task_callback=admina_task_callback)
+```
+
+See [full integration docs](docs/guides/integrations.md) for details.
+
+## Hybrid Python + Rust Engine
+
+The Rust core engine is an optional accelerator. `pip install admina-framework`
+ships only the pure-Python implementation; to enable the Rust engine
+build `admina_core` separately (`maturin develop --release
+--manifest-path core-rust/Cargo.toml`, see [CONTRIBUTING.md](CONTRIBUTING.md)).
+At runtime Admina auto-detects whichever is available and falls back
+transparently to Python if the Rust extension is not installed.
+
+Measured numbers below assume the Rust engine is loaded:
+
+```
+Component          Rust (median)   P95        P99
+-----------------  -------------   ---------  ---------
+Firewall (regex)   2.08us          2.33us     2.50us
+PII Scanner        0.62us          0.67us     0.71us
+Loop Breaker       2.38us          2.67us     2.75us
+Hash Chain         1.00us          1.12us     1.25us
+-----------------  -------------   ---------  ---------
+4-Domain pipeline  6.25us          7.04us     7.29us
+```
+
+<details>
+<summary>Rust vs Python comparison (click to expand)</summary>
+
+```
+Component          Python (median)   Rust (median)   Speedup
+-----------------  ---------------   -------------   --------
+Firewall           7.79us            2.08us          3.7x
+PII (regex-only)   8.21us            0.62us          13.2x
+PII (with spaCy)   1 992us           0.62us          3 213x
+Loop (sklearn)     505us             2.38us          212x
+-----------------  ---------------   -------------   --------
+Full pipeline      2 261us           5.21us          434x
+```
+
+</details>
+
+## Traffic Simulator
+
+Generate realistic governance traffic to test and demo the platform:
+
+```bash
+# Start the proxy
+docker compose up -d
+
+# Default: 60s at 2 req/s
+python scripts/simulate.py
+
+# Intense: 5 minutes at 10 req/s
+python scripts/simulate.py --duration 300 --rate 10
+```
+
+Generates a weighted mix of: clean MCP requests, injection attempts, PII content, loop triggers, REST validate/audit calls, EU AI Act classifications, and dashboard reads. Colored terminal output with per-event action and summary counters.
+
+## Project Structure
+
+```
+admina/
++-- admina/                 SDK package (GovernedModel, GovernedData, GovernedAgent, ComplianceKit)
+|   +-- plugins/            Plugin base classes + registry
++-- domains/                4 governance domains
+|   +-- data_sovereignty/   PII, residency, classification
+|   +-- ai_infra/           LLM engine, RAG pipeline, Web UI
+|   +-- agent_security/     Firewall, loop breaker, proxy
+|   +-- compliance/         EU AI Act, forensic, OTEL
++-- plugins/builtin/        Reference plugin implementations
+|   +-- adapters/           Ollama, OpenAI
+|   +-- connectors/         ChromaDB, Filesystem
+|   +-- domains/            GuardrailsAI
+|   +-- compliance/         EU AI Act template
+|   +-- transports/         MCP, HTTP REST
+|   +-- forensic/           MinIO, Filesystem
+|   +-- auth/               API Key
+|   +-- pii/                spaCy + Regex
+|   +-- alerts/             Log, Webhook
++-- proxy/                  FastAPI proxy + Rust engine bridge
+|   +-- api/                Dashboard + integration REST endpoints
++-- cli/                    CLI commands (init, dev, plugin)
++-- core/                   Config, types, event bus
++-- core-rust/              Rust governance engines (PyO3)
++-- dashboard/              Real-time governance web UI
++-- integrations/
+|   +-- openclaw/           OpenClaw governance skill
+|   +-- n8n/                n8n community nodes
++-- tests/                  800+ tests (pytest)
++-- docker-compose.yml      Full stack deployment (9 containers)
+```
+
+## API
+
+```bash
+# Health check (always public)
+curl http://localhost:8080/health
+
+# Governance stats
+curl http://localhost:8080/api/stats -H "X-API-Key: $ADMINA_API_KEY"
+
+# Proxy an MCP call (all governance domains applied)
+curl -X POST http://localhost:8080/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{...}}'
+
+# Validate content (REST API for integrations)
+curl -X POST http://localhost:8080/api/v1/validate \
+  -H "Content-Type: application/json" \
+  -d '{"content": "Check this text for governance issues"}'
+
+# Audit an action (forensic logging)
+curl -X POST http://localhost:8080/api/v1/audit \
+  -H "Content-Type: application/json" \
+  -d '{"event": {"action": "llm_call", "status": "success"}}'
+
+# EU AI Act risk classification
+curl -X POST http://localhost:8080/api/compliance/classify \
+  -H "Content-Type: application/json" \
+  -d '{"description":"AI credit scoring","use_case":"lending","data_types":["financial"]}'
+
+# Dashboard governance score
+curl http://localhost:8080/api/dashboard/score
+```
+
+## Infrastructure & Services
+
+The full stack (`docker compose up`) runs 9 containers:
+
+| Port | Service | Description |
+|------|---------|-------------|
+| `8080` | Proxy | MCP proxy + REST API + OpenAPI docs |
+| `3000` | Dashboard | Real-time governance web UI |
+| `3001` | Grafana | Metrics dashboards |
+| `9090` | MinIO Console | Forensic storage browser |
+| `4317` | OTEL Collector | OTLP gRPC ingestion |
+
+ClickHouse and Redis are internal only (not exposed to host).
+
+## Project documents
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, testing, and pull request workflow
+- [MODEL_CARD.md](MODEL_CARD.md) — transparency artifact for every Admina governance component (intended use, scope, limitations, known failure modes), aligned with EU AI Act Art. 13 and NIST AI RMF
+- [ROADMAP.md](ROADMAP.md) — planned milestones from 0.9.x to 1.0 and beyond
+- [CHANGELOG.md](CHANGELOG.md) — release notes
+- [SECURITY.md](SECURITY.md) — coordinated disclosure policy
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — Contributor Covenant 2.1
+
+Admina is Apache 2.0. Contributions are welcome.
+
+## License
+
+Copyright © 2025–2026 [Stefano Noferi](https://github.com/stefanoferi) & Admina contributors
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full text.
+
+---
+
+<p align="center">
+  <img src="https://admina.org/admina-heimdall-the-governance-owl.png" alt="Heimdall — the Governance Owl" width="80" /><br/>
+  <em>Heimdall — the Governance Owl</em><br/><br/>
+  <strong>admina.org</strong> · Created by Stefano Noferi · Pisa, Italy
+</p>

admina_framework-0.9.0.dist-info/RECORD

@@ -0,0 +1,102 @@
+admina/__init__.py,sha256=zgqAKo06cFkYLaOlzKZDuDd6_XL6AYHeDeAqYsgMt-Y,1038
+admina/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+admina/cli/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/cli/main.py,sha256=01GE__NcYktINn1CvdzUEfZZhwM1wxpTOMkCpqxp0HU,51853
+admina/cli/commands/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/cli/templates/admina.yaml.j2,sha256=sSUrySnbze7_GMtTaN47Cy429bDt3_XpNHO9uniaKSo,1601
+admina/cli/templates/docker-compose.yml.j2,sha256=XDgmhYGx-DO3bVlmsG-6eAAOoyxyYdH7cm5nDdbkk3o,7728
+admina/cli/templates/env.j2,sha256=E2Xcoe6V6-pI1x-JPiFfRjDqhB5SraN59ExqzUG1F5k,285
+admina/cli/templates/main.py.j2,sha256=DEcxkUTE-sj6r4UF0nmXZaTCDTJk4kT9ZPkMSJnANrw,3330
+admina/cli/templates/plugin.py.j2,sha256=pXOPsjH20VJ8tmm-vcLuKAhzJs18DBctB34Ie9HSUpo,5250
+admina/cli/templates/plugin_pyproject.toml.j2,sha256=7VDmvJTa1b78kS5y8tv10BviySZbwRnie2LQng3x1uM,350
+admina/cli/templates/plugin_readme.md.j2,sha256=4x-M-q2WC26mNFaUfa9Sqp2JtVESr1L-sLXPKxA9ZJQ,337
+admina/cli/templates/plugin_test.py.j2,sha256=gIwDmuFOihf7oxLIhAYt66soskP3ItZh7i6XskuAoMk,1581
+admina/core/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/core/config.py,sha256=6tdYBuQDDuPvSav1sPj_K-SVsDZO_NE_SZ-aMJGDbGE,15547
+admina/core/event_bus.py,sha256=tvNagefrKI-vgPD4dj_Quzz3bFcKfEEXBEfInzDGrRg,3810
+admina/core/secrets.py,sha256=AiGhydwGuWBq8wliuMZgE24fdyDzcBs8nWr1tDFnqaQ,9155
+admina/core/types.py,sha256=ywe--Xj3i7ev-5G2Y3LtznhL7HvwfB9UwEqnolRFK1s,4431
+admina/dashboard/__init__.py,sha256=MPJURW2eIHULmz7xxOk5lT49w80NjzCU4hq5-h7hqqE,332
+admina/dashboard/static/heimdall.png,sha256=0eoSHBV1YAu3JxgVuR63zYSG8HLHOZExloeEu0YG5pQ,421783
+admina/dashboard/static/index.html,sha256=l26hqcLD2PAoG59LNS9szWOloQPOobNL9W65aYLCW9k,52134
+admina/dashboard/static/vendor/alpinejs.min.js,sha256=tgDjY9mdlURNtUrL-y3v_smueSqpmgkim82geOW1VkM,44758
+admina/domains/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/domains/agent_security/__init__.py,sha256=_x8VhK9mGrJsS6SLjEsVPYVD3WPr_gsVXurZX7MoQqU,1437
+admina/domains/agent_security/firewall.py,sha256=3m674SS2r_rRGtDStOMwsMs46ntvyvwYQelA5QAlts4,23733
+admina/domains/agent_security/loop_breaker.py,sha256=xAJRLQ1QwHWH2ZFxCxKpcgq4ed1FRIO5ubnhqERo3pc,6482
+admina/domains/ai_infra/__init__.py,sha256=aRrrpZnHQbH8mA8T-eGFBcT2AXms6dg8H8dP8wyFnVI,1793
+admina/domains/ai_infra/llm_engine.py,sha256=ARJ1CDJ8HwIBheT5kGAwciXEhDb1m8wuv3er-30hpJE,15296
+admina/domains/ai_infra/rag.py,sha256=cyuRPJwZVpV064fa-HqucAdepk3GHAAIL4EOGhIJnbQ,26610
+admina/domains/ai_infra/webui.py,sha256=B8cZJk99hw9yphAeZ2mHgdlljQcKvQX34O_K_SUNgPQ,9731
+admina/domains/compliance/__init__.py,sha256=hAfBmxlv3RmsiMLVq5Ha7t0kwz65HzIRwslOEpmUet0,3292
+admina/domains/compliance/cross_regulation.py,sha256=oBhkQ48oO9vRbqbj7fLa7xDP9VAOcrhTMTyFVxUFmWw,11971
+admina/domains/compliance/eu_ai_act.py,sha256=3qmCsiYB088_8iLMfL_c3imWLQKFfA7o3L5K6EJ5Wrs,13433
+admina/domains/compliance/forensic.py,sha256=-NXLyEOUHaPU_5HhqLC11oVXKOPirJRgAltS3cewAas,15699
+admina/domains/compliance/gdpr.py,sha256=dHZ2zHVxuIKvVMd3cTUOEmf8NcNqBK8b4i6fyMRk-SA,12471
+admina/domains/compliance/nis2.py,sha256=GBIBAuMk8GWNtzdHUsqY_HCXxZv-XS_gqOSd6-89F38,9555
+admina/domains/compliance/oisg.py,sha256=BfKEIdTVnJs9CwyZ1ixn_XDpqAVF75M5Woh7UG2hYPE,21799
+admina/domains/compliance/otel.py,sha256=Xykos-gd-UKgSWJhI1f2zPErjy9F7YyZ8saRaVnfO70,3719
+admina/domains/data_sovereignty/__init__.py,sha256=-FlrmIhJCWyZV1MgGEdsiXvz8OsI9KLshKcvuD4V14c,1527
+admina/domains/data_sovereignty/classification.py,sha256=HzKGRVyY35C1Rhlpg_xTCRnMrFya-TdeM9fgqX4fvgY,3408
+admina/domains/data_sovereignty/pii.py,sha256=10kpXncjEt046EEXwUmyUijNm-NY2svZdt2Wpz8FfBg,10322
+admina/domains/data_sovereignty/residency.py,sha256=sJe5eFmDrLC38wcyZAA5IPjnMPzjjyW24fnWR4knTM0,3998
+admina/integrations/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/integrations/_engines.py,sha256=8M03Ml8RIcD34S7nYOWgMa4ycxUxCfu-Jp9cG3vtTT0,1912
+admina/integrations/cheshirecat/__init__.py,sha256=plfElOZSwS_udaeU_kpsf3Q6pkl1Rsc8l0y1cBEsdS0,610
+admina/integrations/cheshirecat/admina-plugin/admina_governance.py,sha256=sJ2kLZ97hvaPXcWgsxymVxUakdTmyJDxB9Sr54g3qgI,6967
+admina/integrations/crewai/__init__.py,sha256=plfElOZSwS_udaeU_kpsf3Q6pkl1Rsc8l0y1cBEsdS0,610
+admina/integrations/crewai/callbacks.py,sha256=IcAr-ZGb55dsTs-jiIphFnNNArPFzVBbOsvqIos-Cds,11011
+admina/integrations/langchain/__init__.py,sha256=plfElOZSwS_udaeU_kpsf3Q6pkl1Rsc8l0y1cBEsdS0,610
+admina/integrations/langchain/callbacks.py,sha256=rNatIShLzJsoDIwwzmmUNNrTnDV-b_NKd2Zxh-_VHq0,11435
+admina/integrations/n8n/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/integrations/openclaw/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/__init__.py,sha256=wZt7kaNCvvyby7Di54ye6cLjQHkZpr-qoNoUr6GygR8,1441
+admina/plugins/base.py,sha256=RYKYYBCx5B6JaHXzMzMJcXOyxx-_0fRjBJrF-O6TDkg,20309
+admina/plugins/registry.py,sha256=8e7DeRZEfh_RtuSfz02pnFh8bdfNGKYG7ZREMXgrXQw,12951
+admina/plugins/builtin/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/builtin/adapters/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/builtin/adapters/ollama.py,sha256=3VvVs8ZY1rMJtHSYitZo0e6rIC1ZJMLBah4RqTJ-S1g,4200
+admina/plugins/builtin/adapters/openai.py,sha256=3N9I4fV77u1TU6TMe0hcctyfQ3IlN7ok5b7jS-vSpF4,4942
+admina/plugins/builtin/alerts/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/builtin/alerts/log.py,sha256=sHPLKm6cqlJvo85OxXWKtpXFNURvP6CDY0Q-0fzxRi4,1939
+admina/plugins/builtin/alerts/webhook.py,sha256=2uvuiY-yig-SM5tuhhgb1-AwGy3i8AIDcyRDZ1kZha8,3556
+admina/plugins/builtin/auth/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/builtin/auth/apikey.py,sha256=-O1-Aoqtvo8UBAUUHjnDWd5OpjolSdoOC1SU9ztVHDE,4934
+admina/plugins/builtin/compliance/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/builtin/compliance/eu_ai_act.py,sha256=kxDNVrb6KlL2OlfJL5dakwTdtGF9xfeXeqstSgqylCs,6326
+admina/plugins/builtin/connectors/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/builtin/connectors/chromadb.py,sha256=yDzXfLqt5uH7CY7f44k6ZsKcUu6-wEWy4x7JdPBBstc,4679
+admina/plugins/builtin/connectors/filesystem.py,sha256=C_1R7y8GoWuv8UQ86xDpQZeTV1ZnB1-JEUr8vovo0ug,3498
+admina/plugins/builtin/forensic/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/builtin/forensic/filesystem.py,sha256=KR8Y0SXrtbDKZZizk-1HhUoBT3RTkd7pxWisCPD_sF4,5690
+admina/plugins/builtin/forensic/minio.py,sha256=Q4Hvzrh-thyBSE34Qzq80QoMkHrNZuavZJN6PqECOcI,6021
+admina/plugins/builtin/guards/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+admina/plugins/builtin/guards/guardrailsai_guard.py,sha256=gwsuvD11QU78P6fITCb0BVISXaifPvrfLkNXghHjMYg,6361
+admina/plugins/builtin/pii/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/builtin/pii/spacy_regex.py,sha256=zLnWCgw5WpRfPBmPk8PHFRMrP15qTSI1hJh9CRH5ve0,5422
+admina/plugins/builtin/transports/__init__.py,sha256=zPw-YCDoFboSrXedS07rXp6Bzv20VHzhuZOf2kq0gsE,611
+admina/plugins/builtin/transports/http_rest.py,sha256=OnIDDKRKWZXN6ixh9FxvftyiE1j7UK2GL2vOIUBu37A,3274
+admina/plugins/builtin/transports/mcp.py,sha256=TB_X-yEVKmCKYFLJ8v5pufKp2LiuCB9m0PN68NcVtBA,5297
+admina/proxy/__init__.py,sha256=VTZK_hqAR0Xkjm4i5VcXAEHMMCsZouZL5ywkr_uBJTI,637
+admina/proxy/config.py,sha256=Q-q5QL27lokIh2sQhMLau8E8fOA5Eoj4KpVPwl5tGnA,8670
+admina/proxy/engine_bridge.py,sha256=gMmz_iOuclKEMdl1-411KG2D0bM9yJiDEhk1fLQQnQY,10063
+admina/proxy/governance.py,sha256=092-KHvmQ1Bo3_Wauk_wbMnkkynFnHAOlBXC_odJjSw,8233
+admina/proxy/main.py,sha256=S_lpeKGelr2GoFWPT23VJcljAzgK80_qvcrshfPfCw4,58046
+admina/proxy/multi_upstream.py,sha256=BeDjubYAt-_FBacCOFKWBpIiWn5bYxzUOoH5Vg0XMHc,5620
+admina/proxy/state.py,sha256=bM2I2eg4GlrjtPxh8Yip60_8ThH3PieN5NByEbC3WF0,3418
+admina/proxy/api/__init__.py,sha256=iUfA2ZbFFqFm5OtBqP4KLOAcYVXyNtJXddm0GQ029Yo,723
+admina/proxy/api/dashboard.py,sha256=jIXUjCHp3XvZHdGH1BIRNcSxc6NhwIxSZmBYAfpgz5c,38775
+admina/proxy/api/integration.py,sha256=XgGKxW3GdPPHjvo4Jqy4Upxi47CWINrpBG-AhDVJ0A4,5052
+admina/sdk/__init__.py,sha256=nSsohr6iPt5iw3bEkm735UxQph3GfE_mVoV6JIcZX-Y,1093
+admina/sdk/_compat.py,sha256=5_M9gSpEHKdX-hfTV1wBMqg5jDiAr_RNMBFQ8vMWhVw,1472
+admina/sdk/compliance_kit.py,sha256=4OfR8miYh9-n5_yraj6X9k6lh9FGf9aZganFiQxig9Q,11780
+admina/sdk/governed_agent.py,sha256=AoL8oBeGEiwAt0jc-u-BRcHKr8CJpDjfnPY7AO_WpCM,12373
+admina/sdk/governed_data.py,sha256=3ZwgE6si0czfFvSW8yzEITHsjzxK95ho5x-zUdc56xg,14533
+admina/sdk/governed_model.py,sha256=4l5IuuQwbqfNFBbfCVra1k_YMLjoSpsNfe9fhMB-VKs,8051
+admina_framework-0.9.0.dist-info/licenses/LICENSE,sha256=89WG7dTGIbOGDHpfhHBV90HTgc6Og03pCsbhmnAttyc,10798
+admina_framework-0.9.0.dist-info/licenses/NOTICE,sha256=49HL9ZdvC0wJlwS2hI0zLrLNfqjWVGPoKzm99xN1LOU,631
+admina_framework-0.9.0.dist-info/METADATA,sha256=9hzgO7z5DystSZdevJvCpLALEHzuOdej5P4r90YZml8,24916
+admina_framework-0.9.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+admina_framework-0.9.0.dist-info/entry_points.txt,sha256=Sf1t52Q-gi1LvznRHag4oYdFOWOlLv3H_ywHC-O0vv4,47
+admina_framework-0.9.0.dist-info/top_level.txt,sha256=Ome4T3fbY7vR9rof7oSNpag8IDD3hU1pb7KJmycNTc8,7
+admina_framework-0.9.0.dist-info/RECORD,,