adminA 0.14.2__tar.gz → 0.15.0__tar.gz

{admina-0.14.2/admina.egg-info → admina-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: admina
-Version: 0.14.2
+Version: 0.15.0
 Summary: Admina — governed AI development framework
 Author-email: Stefano Noferi <info@admina.org>
 Maintainer-email: Stefano Noferi <info@admina.org>
@@ -59,7 +59,7 @@ 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: rust
-Requires-Dist: admina-core<0.15,>=0.14.0; extra == "rust"
+Requires-Dist: admina-core<0.16,>=0.15.0; extra == "rust"
 Provides-Extra: full
 Requires-Dist: admina[nlp,proxy,telemetry]; extra == "full"
 Provides-Extra: openai
@@ -210,48 +210,61 @@ report = kit.gap_analysis(risk_category="high", current_compliance={...})
 ```bash
 # Recommended for new users: SDK + proxy + dashboard.
 # Lets you run `admina dev` and see the dashboard out of the box.
-pip install "admina[proxy]"
+uv add "admina[proxy]"
+# in an existing virtual environment: uv pip install "admina[proxy]"
+# with pip:                           pip install "admina[proxy]"
+
+# The `admina` command on your PATH, outside any project:
+uv tool install "admina[proxy]"
 
 # Everything (proxy + NLP + telemetry). Use this if you also want
 # spaCy-based NER for PII detection or OpenTelemetry export.
-pip install "admina[full]"
-python -m spacy download en_core_web_sm   # for [full] only
+uv add "admina[full]"
+# for [full] only: the spaCy English model, declared in the project
+uv add "en-core-web-sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl"
 
 # Model-adapter provider SDKs (per-provider extras):
-pip install "admina[openai]"      # openai>=1.0
-pip install "admina[ollama]"      # ollama>=0.3
-pip install "admina[anthropic]"   # anthropic>=0.39
-pip install "admina[mistral]"     # mistralai>=1.0
-pip install "admina[gemini]"      # google-genai>=1.0
-pip install "admina[bedrock]"     # boto3>=1.34 (AWS Bedrock)
+uv add "admina[openai]"      # openai>=1.0
+uv add "admina[ollama]"      # ollama>=0.3
+uv add "admina[anthropic]"   # anthropic>=0.39
+uv add "admina[mistral]"     # mistralai>=1.0
+uv add "admina[gemini]"      # google-genai>=1.0
+uv add "admina[bedrock]"     # boto3>=1.34 (AWS Bedrock)
 
 # All provider SDKs at once:
-pip install "admina[adapters]"
+uv add "admina[adapters]"
 
 # Everything (proxy + NLP + telemetry + all adapters):
-pip install "admina[all]"
-python -m spacy download en_core_web_sm   # for [all] only
+uv add "admina[all]"
+# for [all] only: the spaCy English model, as for [full]
 
 # Optional: Rust-accelerated engine (auto-detected at runtime).
 # Opt-in extra — pulls in the admina-core wheel from PyPI.
-pip install "admina[rust]"
+uv add "admina[rust]"
 
 # The proxy for the OpenAI-compatible gateway only: without Redis,
 # ClickHouse, boto3 and the scientific stack (see "Embedded deployment").
-pip install "admina[proxy-minimal]"
+uv add "admina[proxy-minimal]"
 
 # Advanced: SDK only (no proxy, no dashboard, no `admina dev`).
 # Use this when embedding the SDK into another service and you don't
 # need the local dev server.
-pip install admina
+uv add admina
 ```
 
-> The PyPI distribution name is `admina`; the Python import
-> name is `admina` (e.g. `from admina import GovernedModel`). This is
-> a normal Python pattern — same as `python-dateutil` → `import dateutil`.
+> Each `uv add` line above adds a dependency to the `pyproject.toml` of the
+> current project (`uv init` creates one). In an existing virtual environment,
+> use `uv pip install` with the same argument; with pip, use `pip install`
+> with the same argument (for example `pip install "admina[full]"`), and
+> `python -m spacy download en_core_web_sm` for the spaCy model.
+> To upgrade: `uv add --upgrade-package admina "admina[proxy]"`,
+> `uv pip install -U "admina[proxy]"` or `pip install -U "admina[proxy]"`.
+
+> The PyPI distribution and the Python module are both named `admina`
+> (e.g. `from admina import GovernedModel`).
 
 > The Rust engine is an **optional, opt-in** accelerator. The default
-> `pip install admina` ships only the pure-Python implementation;
+> `admina` package ships only the pure-Python implementation;
 > `admina[rust]` adds the `admina-core` wheel, which Admina
 > auto-detects at runtime: under `ADMINA_ENGINE=auto` (the default) the
 > firewall and the loop breaker run on Rust whenever it is installed, as in
@@ -271,16 +284,21 @@ git clone https://github.com/admina-org/admina.git
 cd admina
 
 # Recommended: proxy + dashboard + infra deps (enables `admina dev`)
-pip install -e ".[proxy]"
+uv sync --extra proxy
+# in an existing virtual environment: uv pip install -e ".[proxy]"
+# with pip:                           pip install -e ".[proxy]"
 
 # Everything (proxy + NLP + telemetry)
-pip install -e ".[full]"
+uv sync --extra full
 
 # All model-adapter SDKs
-pip install -e ".[adapters]"
+uv sync --extra adapters
 
 # Everything (proxy + NLP + telemetry + all adapters)
-pip install -e ".[all]"
+uv sync --extra all
+
+# `uv sync` installs into .venv/: activate it (source .venv/bin/activate)
+# or prefix the commands below with `uv run`.
 
 # CLI workflow
 admina init my-project   # Scaffold a governed AI project
@@ -295,7 +313,7 @@ docker compose up --build        # Credentials printed at bootstrap
 # and pull a model first: ollama pull llama3.1:8b
 
 # Advanced: SDK only (no proxy, no dashboard)
-pip install -e .
+uv sync --no-dev         # with pip: pip install -e .
 python -c "from admina import GovernedModel; print('SDK ready')"
 ```
 
@@ -346,7 +364,7 @@ from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
 
 ## Plugin System
 
-9 plugin interfaces, auto-discovered from `plugins/builtin/` or installed via CLI:
+10 plugin interfaces, auto-discovered from `plugins/builtin/` or installed via CLI:
 
 | Interface | Builtin implementations |
 |-----------|------------------------|
@@ -357,11 +375,12 @@ from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
 | Transport Adapter | MCP, HTTP REST |
 | Forensic Store | Filesystem, S3-compatible (boto3 — AWS S3, MinIO, R2, …) |
 | Auth Provider | API Key |
-| PII Engine | spaCy + Regex (default), Microsoft Presidio (`pip install admina[presidio]`, `ADMINA_PII_ENGINE=presidio`); engines of other packages through the `admina.pii_engines` entry-point group (see [PII engines](#pii-engines)) |
+| PII Engine | spaCy + Regex (default), Microsoft Presidio (`uv add "admina[presidio]"` or `pip install "admina[presidio]"`, `ADMINA_PII_ENGINE=presidio`); engines of other packages through the `admina.pii_engines` entry-point group (see [PII engines](#pii-engines)) |
 | Alert Channel | Log, Webhook |
+| Execution Sandbox | Docker / Podman (runc or runsc), see [Execution sandbox](#execution-sandbox) |
 
 Model adapters lazy-import their provider SDK, so install the ones you
-use: `pip install admina[adapters]` for all of them, or a
+use: `uv add "admina[adapters]"` (with pip: `pip install "admina[adapters]"`) for all of them, or a
 single provider (`[openai]`, `[ollama]`, `[anthropic]`, `[mistral]`,
 `[gemini]`, `[bedrock]`). vLLM has no extra of its own — it serves an
 OpenAI-compatible API and subclasses the OpenAI adapter, so install
@@ -460,9 +479,9 @@ stops when they are not set.
 
 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)
+- **Governance Score** — 0-100 composite metric (data residency, audit coverage, attack rate, forensic integrity, EU AI Act compliance). When the latest EU AI Act assessment is `NOT_APPLICABLE` (a limited- or minimal-risk system), that component is `null` in `GET /api/dashboard/score`, listed in `not_applicable`, and the score is rescaled over the other components
 - **Live Feed** — streaming governance events via WebSocket
-- **Compliance Gaps** — EU AI Act gap analysis with article-level detail
+- **Compliance Gaps** — EU AI Act gap analysis with article-level detail; a limited- or minimal-risk system is shown as "Articles 9–15 not required"
 - **Infrastructure Health** — proxy, Redis, forensic store, ClickHouse, OTEL status
 
 API backend: `GET /api/dashboard/score`, `/feed`, `/compliance`, `/sovereignty`, `/infra`, `/models`
@@ -794,6 +813,36 @@ the message text of `POST /v1/chat/completions`, in characters (the text of
 every message, as scanned); longer requests get 413 (`invalid_request_error`,
 code `prompt_too_long`) before any governance check.
 
+### MCP routing to several servers
+
+`/mcp` forwards to `UPSTREAM_MCP_URL`. To put several MCP servers behind
+one proxy, set `ROUTING_CONFIG_PATH` to a routing file (JSON, or YAML with a
+`.yaml`/`.yml` suffix):
+
+```yaml
+default_upstream: http://localhost:9000
+routes:
+  github:
+    upstream_url: http://github-mcp:8000/mcp
+    headers: { Authorization: "Bearer <token>" }
+    tools: [create_issue, git_push]
+  files:
+    upstream_url: http://files-mcp:8000/mcp
+    tools: [read_file, write_file]
+```
+
+A request picks a route in one of two ways:
+
+- **By path**: `POST /mcp/route/<name>` goes to that route's `upstream_url`.
+- **By tool name**: a call on `/mcp` whose `params.name` is listed in a
+  route's `tools` goes to that route (`tools/call` for `git_push` above goes
+  to `github`). A tool not listed by any route goes to `UPSTREAM_MCP_URL`.
+
+`tools` is a list of tool names; anything else, or a tool listed by two
+routes, stops the proxy at startup. The tools are declared, not discovered:
+list each tool a server provides that should be routed to it. `GET /api/stats`
+reports the routes and the number of mapped tools under `routing`.
+
 ### PII engines
 
 `ADMINA_PII_ENGINE` (or `pii_engine` in `admina.yaml`, default `spacy-regex`)
@@ -1061,7 +1110,7 @@ attempt. The `proxy-minimal` extra installs the proxy without Redis,
 ClickHouse, boto3, typer and the scientific stack of the Python loop breaker:
 
 ```bash
-pip install "admina[proxy-minimal]"
+uv pip install "admina[proxy-minimal]"   # with pip: pip install "admina[proxy-minimal]"
 ADMINA_ENABLED_SURFACES=gateway REDIS_URL= CLICKHOUSE_HOST= \
   ADMINA_API_KEY_FILE=/run/secrets/admina_api_key \
   uvicorn admina.proxy.main:app --host 0.0.0.0 --port 8080
@@ -1206,6 +1255,53 @@ connection is made for telemetry.
 `ADMINA_API_KEY` or `ADMINA_API_KEY_FILE` and prints only whether the key
 is set, never any part of it.
 
+### Execution sandbox
+
+Admina can execute the tool calls it allows instead of forwarding them:
+a tool declared under `domains.agent_security.sandbox.tools` (for example
+a `python_exec` code interpreter) runs in a fresh container per call, with
+no network, a read-only root filesystem, an unprivileged user, no
+capabilities and memory, CPU, process and disk limits; the container is
+removed afterwards. Off by default.
+
+```yaml
+domains:
+  agent_security:
+    sandbox:
+      enabled: true
+      provider: docker          # the built-in provider; binary: podman in plugin_config.docker
+      runtime: runc             # runsc: gVisor, registered with the engine (Linux)
+      tools:
+        python_exec:
+          profile: python       # code → /work/main.py, run with python -I
+          timeout_seconds: 10
+          memory_mb: 256
+```
+
+```bash
+docker pull python:3.12-slim@sha256:a6e34c598f2467ed0e9a8d349809fcd8b5c603269512df273a0bb1784edc11b1
+```
+
+On `/mcp`, a `tools/call` of `python_exec` that the pipeline allows is
+executed in the sandbox and never forwarded upstream; the result (stdout,
+stderr, files written to `out/`) goes through PII redaction and the
+response guards like an upstream response, and `tools/list` lists the
+sandboxed tools next to the upstream's. Each execution adds a forensic
+record `<event_id>:sandbox` with hashes and sizes only, a
+`sandbox_execution` bus event, `admina_sandbox_*` metrics and a `sandbox`
+field in `/health`. If the sandbox is unavailable the call is refused with
+`data.reason: sandbox_unavailable`: it is never executed outside it, in any
+fail mode or governance mode. The SDK helper
+`admina.sdk.sandbox.sandbox_upstream` gives `GovernedAgent` the same
+execution.
+
+The sandbox needs a Docker or Podman engine the proxy can reach. Access to
+the Docker socket is equivalent to root on the host: use rootless Docker or
+rootless Podman, or a dedicated host. The example `docker-compose.yml` does
+not mount the socket. `network: egress` is not supported yet. See the
+[execution sandbox guide](docs/guides/execution-sandbox.md) and what it does
+not guarantee in [MODEL_CARD.md §5d](MODEL_CARD.md#5d-execution-sandbox).
+
 ### OpenAI-compatible gateway
 
 The proxy serves an OpenAI-compatible API at `/v1` (`POST /v1/chat/completions`,
@@ -1696,7 +1792,7 @@ ML-based content validation (toxic language, jailbreak, bias, PII via Presidio)
 # 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>
+uv pip install <your-guardrails-ai-wheel>   # with pip: 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.
@@ -1787,9 +1883,9 @@ See [full integration docs](https://github.com/admina-org/admina/blob/main/docs/
 ## Performance — Hybrid Python + Rust engine
 
 The Rust core engine is an optional accelerator. The default
-`pip install admina` ships only the pure-Python implementation;
-enable the Rust engine with the opt-in extra `pip install
-"admina[rust]"` (or build from source for local development —
+`admina` package ships only the pure-Python implementation;
+enable the Rust engine with the opt-in extra `uv add "admina[rust]"`
+(with pip: `pip install "admina[rust]"`) (or build from source for local development —
 `maturin develop --release --manifest-path core-rust/Cargo.toml`, see
 [CONTRIBUTING.md](https://github.com/admina-org/admina/blob/main/CONTRIBUTING.md)). Under `ADMINA_ENGINE=auto` Admina
 runs the Rust firewall and loop breaker when the extension is installed and
@@ -1920,10 +2016,12 @@ production.
 | `ADMINA_CONFIG` | *(empty)* | `admina.yaml` to load (empty: current directory, then package directory) |
 | `ADMINA_ENABLED_SURFACES` | *(empty = all)* | Surfaces served: `gateway`, `mcp`, `integration`, `compliance`, `dashboard` |
 | `UPSTREAM_MCP_URL` | `http://localhost:9000` | Default upstream MCP server |
+| `ROUTING_CONFIG_PATH` | *(empty)* | Routing file for several MCP servers (see [MCP routing to several servers](#mcp-routing-to-several-servers)) |
 | `REDIS_URL` | `redis://localhost:6379/0` | Session state + rate limiting (empty = no Redis) |
 | `CLICKHOUSE_HOST` | `localhost` | Event analytics (empty = no ClickHouse) |
 | `FORENSIC_BACKEND` | `memory` | Forensic store: `memory` \| `filesystem` \| `s3` (else `domains.compliance.forensic.backend` of `admina.yaml`) |
 | `FORENSIC_BASE_DIR` | *(empty)* | Directory of the `filesystem` store (else `domains.compliance.forensic.base_dir`) |
+| `ADMINA_EU_AI_ACT_ASSESSMENTS_PATH` | *(empty)* | JSON file keeping the last 100 EU AI Act assessments across restarts (empty: in memory only; the compose files set it on the `compliance-data` volume) |
 | `ADMINA_FORENSIC_FAIL_MODE` | `open` | A forensic record that cannot be written: `open` (logged, request served) \| `closed` (`503`, not forwarded) |
 | `LOG_LEVEL` | `INFO` | Logging verbosity |
 | `ADMINA_LOG_FORMAT` | `text` | Log output: `text` \| `json` |
@@ -2001,6 +2099,14 @@ 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"]}'
 
+# EU AI Act assessment of a limited-risk system (recorded as NOT_APPLICABLE)
+curl -X POST http://localhost:8080/api/compliance/gap-analysis \
+  -H "Content-Type: application/json" \
+  -d '{"risk_category":"limited","system_name":"Helpdesk bot"}'
+
+# The most recent EU AI Act assessment (404 without one)
+curl http://localhost:8080/api/compliance/gap-analysis/latest
+
 # Dashboard governance score
 curl http://localhost:8080/api/dashboard/score
 ```

{admina-0.14.2 → admina-0.15.0}/README.md

@@ -126,48 +126,61 @@ report = kit.gap_analysis(risk_category="high", current_compliance={...})
 ```bash
 # Recommended for new users: SDK + proxy + dashboard.
 # Lets you run `admina dev` and see the dashboard out of the box.
-pip install "admina[proxy]"
+uv add "admina[proxy]"
+# in an existing virtual environment: uv pip install "admina[proxy]"
+# with pip:                           pip install "admina[proxy]"
+
+# The `admina` command on your PATH, outside any project:
+uv tool install "admina[proxy]"
 
 # Everything (proxy + NLP + telemetry). Use this if you also want
 # spaCy-based NER for PII detection or OpenTelemetry export.
-pip install "admina[full]"
-python -m spacy download en_core_web_sm   # for [full] only
+uv add "admina[full]"
+# for [full] only: the spaCy English model, declared in the project
+uv add "en-core-web-sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl"
 
 # Model-adapter provider SDKs (per-provider extras):
-pip install "admina[openai]"      # openai>=1.0
-pip install "admina[ollama]"      # ollama>=0.3
-pip install "admina[anthropic]"   # anthropic>=0.39
-pip install "admina[mistral]"     # mistralai>=1.0
-pip install "admina[gemini]"      # google-genai>=1.0
-pip install "admina[bedrock]"     # boto3>=1.34 (AWS Bedrock)
+uv add "admina[openai]"      # openai>=1.0
+uv add "admina[ollama]"      # ollama>=0.3
+uv add "admina[anthropic]"   # anthropic>=0.39
+uv add "admina[mistral]"     # mistralai>=1.0
+uv add "admina[gemini]"      # google-genai>=1.0
+uv add "admina[bedrock]"     # boto3>=1.34 (AWS Bedrock)
 
 # All provider SDKs at once:
-pip install "admina[adapters]"
+uv add "admina[adapters]"
 
 # Everything (proxy + NLP + telemetry + all adapters):
-pip install "admina[all]"
-python -m spacy download en_core_web_sm   # for [all] only
+uv add "admina[all]"
+# for [all] only: the spaCy English model, as for [full]
 
 # Optional: Rust-accelerated engine (auto-detected at runtime).
 # Opt-in extra — pulls in the admina-core wheel from PyPI.
-pip install "admina[rust]"
+uv add "admina[rust]"
 
 # The proxy for the OpenAI-compatible gateway only: without Redis,
 # ClickHouse, boto3 and the scientific stack (see "Embedded deployment").
-pip install "admina[proxy-minimal]"
+uv add "admina[proxy-minimal]"
 
 # Advanced: SDK only (no proxy, no dashboard, no `admina dev`).
 # Use this when embedding the SDK into another service and you don't
 # need the local dev server.
-pip install admina
+uv add admina
 ```
 
-> The PyPI distribution name is `admina`; the Python import
-> name is `admina` (e.g. `from admina import GovernedModel`). This is
-> a normal Python pattern — same as `python-dateutil` → `import dateutil`.
+> Each `uv add` line above adds a dependency to the `pyproject.toml` of the
+> current project (`uv init` creates one). In an existing virtual environment,
+> use `uv pip install` with the same argument; with pip, use `pip install`
+> with the same argument (for example `pip install "admina[full]"`), and
+> `python -m spacy download en_core_web_sm` for the spaCy model.
+> To upgrade: `uv add --upgrade-package admina "admina[proxy]"`,
+> `uv pip install -U "admina[proxy]"` or `pip install -U "admina[proxy]"`.
+
+> The PyPI distribution and the Python module are both named `admina`
+> (e.g. `from admina import GovernedModel`).
 
 > The Rust engine is an **optional, opt-in** accelerator. The default
-> `pip install admina` ships only the pure-Python implementation;
+> `admina` package ships only the pure-Python implementation;
 > `admina[rust]` adds the `admina-core` wheel, which Admina
 > auto-detects at runtime: under `ADMINA_ENGINE=auto` (the default) the
 > firewall and the loop breaker run on Rust whenever it is installed, as in
@@ -187,16 +200,21 @@ git clone https://github.com/admina-org/admina.git
 cd admina
 
 # Recommended: proxy + dashboard + infra deps (enables `admina dev`)
-pip install -e ".[proxy]"
+uv sync --extra proxy
+# in an existing virtual environment: uv pip install -e ".[proxy]"
+# with pip:                           pip install -e ".[proxy]"
 
 # Everything (proxy + NLP + telemetry)
-pip install -e ".[full]"
+uv sync --extra full
 
 # All model-adapter SDKs
-pip install -e ".[adapters]"
+uv sync --extra adapters
 
 # Everything (proxy + NLP + telemetry + all adapters)
-pip install -e ".[all]"
+uv sync --extra all
+
+# `uv sync` installs into .venv/: activate it (source .venv/bin/activate)
+# or prefix the commands below with `uv run`.
 
 # CLI workflow
 admina init my-project   # Scaffold a governed AI project
@@ -211,7 +229,7 @@ docker compose up --build        # Credentials printed at bootstrap
 # and pull a model first: ollama pull llama3.1:8b
 
 # Advanced: SDK only (no proxy, no dashboard)
-pip install -e .
+uv sync --no-dev         # with pip: pip install -e .
 python -c "from admina import GovernedModel; print('SDK ready')"
 ```
 
@@ -262,7 +280,7 @@ from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
 
 ## Plugin System
 
-9 plugin interfaces, auto-discovered from `plugins/builtin/` or installed via CLI:
+10 plugin interfaces, auto-discovered from `plugins/builtin/` or installed via CLI:
 
 | Interface | Builtin implementations |
 |-----------|------------------------|
@@ -273,11 +291,12 @@ from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
 | Transport Adapter | MCP, HTTP REST |
 | Forensic Store | Filesystem, S3-compatible (boto3 — AWS S3, MinIO, R2, …) |
 | Auth Provider | API Key |
-| PII Engine | spaCy + Regex (default), Microsoft Presidio (`pip install admina[presidio]`, `ADMINA_PII_ENGINE=presidio`); engines of other packages through the `admina.pii_engines` entry-point group (see [PII engines](#pii-engines)) |
+| PII Engine | spaCy + Regex (default), Microsoft Presidio (`uv add "admina[presidio]"` or `pip install "admina[presidio]"`, `ADMINA_PII_ENGINE=presidio`); engines of other packages through the `admina.pii_engines` entry-point group (see [PII engines](#pii-engines)) |
 | Alert Channel | Log, Webhook |
+| Execution Sandbox | Docker / Podman (runc or runsc), see [Execution sandbox](#execution-sandbox) |
 
 Model adapters lazy-import their provider SDK, so install the ones you
-use: `pip install admina[adapters]` for all of them, or a
+use: `uv add "admina[adapters]"` (with pip: `pip install "admina[adapters]"`) for all of them, or a
 single provider (`[openai]`, `[ollama]`, `[anthropic]`, `[mistral]`,
 `[gemini]`, `[bedrock]`). vLLM has no extra of its own — it serves an
 OpenAI-compatible API and subclasses the OpenAI adapter, so install
@@ -376,9 +395,9 @@ stops when they are not set.
 
 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)
+- **Governance Score** — 0-100 composite metric (data residency, audit coverage, attack rate, forensic integrity, EU AI Act compliance). When the latest EU AI Act assessment is `NOT_APPLICABLE` (a limited- or minimal-risk system), that component is `null` in `GET /api/dashboard/score`, listed in `not_applicable`, and the score is rescaled over the other components
 - **Live Feed** — streaming governance events via WebSocket
-- **Compliance Gaps** — EU AI Act gap analysis with article-level detail
+- **Compliance Gaps** — EU AI Act gap analysis with article-level detail; a limited- or minimal-risk system is shown as "Articles 9–15 not required"
 - **Infrastructure Health** — proxy, Redis, forensic store, ClickHouse, OTEL status
 
 API backend: `GET /api/dashboard/score`, `/feed`, `/compliance`, `/sovereignty`, `/infra`, `/models`
@@ -710,6 +729,36 @@ the message text of `POST /v1/chat/completions`, in characters (the text of
 every message, as scanned); longer requests get 413 (`invalid_request_error`,
 code `prompt_too_long`) before any governance check.
 
+### MCP routing to several servers
+
+`/mcp` forwards to `UPSTREAM_MCP_URL`. To put several MCP servers behind
+one proxy, set `ROUTING_CONFIG_PATH` to a routing file (JSON, or YAML with a
+`.yaml`/`.yml` suffix):
+
+```yaml
+default_upstream: http://localhost:9000
+routes:
+  github:
+    upstream_url: http://github-mcp:8000/mcp
+    headers: { Authorization: "Bearer <token>" }
+    tools: [create_issue, git_push]
+  files:
+    upstream_url: http://files-mcp:8000/mcp
+    tools: [read_file, write_file]
+```
+
+A request picks a route in one of two ways:
+
+- **By path**: `POST /mcp/route/<name>` goes to that route's `upstream_url`.
+- **By tool name**: a call on `/mcp` whose `params.name` is listed in a
+  route's `tools` goes to that route (`tools/call` for `git_push` above goes
+  to `github`). A tool not listed by any route goes to `UPSTREAM_MCP_URL`.
+
+`tools` is a list of tool names; anything else, or a tool listed by two
+routes, stops the proxy at startup. The tools are declared, not discovered:
+list each tool a server provides that should be routed to it. `GET /api/stats`
+reports the routes and the number of mapped tools under `routing`.
+
 ### PII engines
 
 `ADMINA_PII_ENGINE` (or `pii_engine` in `admina.yaml`, default `spacy-regex`)
@@ -977,7 +1026,7 @@ attempt. The `proxy-minimal` extra installs the proxy without Redis,
 ClickHouse, boto3, typer and the scientific stack of the Python loop breaker:
 
 ```bash
-pip install "admina[proxy-minimal]"
+uv pip install "admina[proxy-minimal]"   # with pip: pip install "admina[proxy-minimal]"
 ADMINA_ENABLED_SURFACES=gateway REDIS_URL= CLICKHOUSE_HOST= \
   ADMINA_API_KEY_FILE=/run/secrets/admina_api_key \
   uvicorn admina.proxy.main:app --host 0.0.0.0 --port 8080
@@ -1122,6 +1171,53 @@ connection is made for telemetry.
 `ADMINA_API_KEY` or `ADMINA_API_KEY_FILE` and prints only whether the key
 is set, never any part of it.
 
+### Execution sandbox
+
+Admina can execute the tool calls it allows instead of forwarding them:
+a tool declared under `domains.agent_security.sandbox.tools` (for example
+a `python_exec` code interpreter) runs in a fresh container per call, with
+no network, a read-only root filesystem, an unprivileged user, no
+capabilities and memory, CPU, process and disk limits; the container is
+removed afterwards. Off by default.
+
+```yaml
+domains:
+  agent_security:
+    sandbox:
+      enabled: true
+      provider: docker          # the built-in provider; binary: podman in plugin_config.docker
+      runtime: runc             # runsc: gVisor, registered with the engine (Linux)
+      tools:
+        python_exec:
+          profile: python       # code → /work/main.py, run with python -I
+          timeout_seconds: 10
+          memory_mb: 256
+```
+
+```bash
+docker pull python:3.12-slim@sha256:a6e34c598f2467ed0e9a8d349809fcd8b5c603269512df273a0bb1784edc11b1
+```
+
+On `/mcp`, a `tools/call` of `python_exec` that the pipeline allows is
+executed in the sandbox and never forwarded upstream; the result (stdout,
+stderr, files written to `out/`) goes through PII redaction and the
+response guards like an upstream response, and `tools/list` lists the
+sandboxed tools next to the upstream's. Each execution adds a forensic
+record `<event_id>:sandbox` with hashes and sizes only, a
+`sandbox_execution` bus event, `admina_sandbox_*` metrics and a `sandbox`
+field in `/health`. If the sandbox is unavailable the call is refused with
+`data.reason: sandbox_unavailable`: it is never executed outside it, in any
+fail mode or governance mode. The SDK helper
+`admina.sdk.sandbox.sandbox_upstream` gives `GovernedAgent` the same
+execution.
+
+The sandbox needs a Docker or Podman engine the proxy can reach. Access to
+the Docker socket is equivalent to root on the host: use rootless Docker or
+rootless Podman, or a dedicated host. The example `docker-compose.yml` does
+not mount the socket. `network: egress` is not supported yet. See the
+[execution sandbox guide](docs/guides/execution-sandbox.md) and what it does
+not guarantee in [MODEL_CARD.md §5d](MODEL_CARD.md#5d-execution-sandbox).
+
 ### OpenAI-compatible gateway
 
 The proxy serves an OpenAI-compatible API at `/v1` (`POST /v1/chat/completions`,
@@ -1612,7 +1708,7 @@ ML-based content validation (toxic language, jailbreak, bias, PII via Presidio)
 # 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>
+uv pip install <your-guardrails-ai-wheel>   # with pip: 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.
@@ -1703,9 +1799,9 @@ See [full integration docs](https://github.com/admina-org/admina/blob/main/docs/
 ## Performance — Hybrid Python + Rust engine
 
 The Rust core engine is an optional accelerator. The default
-`pip install admina` ships only the pure-Python implementation;
-enable the Rust engine with the opt-in extra `pip install
-"admina[rust]"` (or build from source for local development —
+`admina` package ships only the pure-Python implementation;
+enable the Rust engine with the opt-in extra `uv add "admina[rust]"`
+(with pip: `pip install "admina[rust]"`) (or build from source for local development —
 `maturin develop --release --manifest-path core-rust/Cargo.toml`, see
 [CONTRIBUTING.md](https://github.com/admina-org/admina/blob/main/CONTRIBUTING.md)). Under `ADMINA_ENGINE=auto` Admina
 runs the Rust firewall and loop breaker when the extension is installed and
@@ -1836,10 +1932,12 @@ production.
 | `ADMINA_CONFIG` | *(empty)* | `admina.yaml` to load (empty: current directory, then package directory) |
 | `ADMINA_ENABLED_SURFACES` | *(empty = all)* | Surfaces served: `gateway`, `mcp`, `integration`, `compliance`, `dashboard` |
 | `UPSTREAM_MCP_URL` | `http://localhost:9000` | Default upstream MCP server |
+| `ROUTING_CONFIG_PATH` | *(empty)* | Routing file for several MCP servers (see [MCP routing to several servers](#mcp-routing-to-several-servers)) |
 | `REDIS_URL` | `redis://localhost:6379/0` | Session state + rate limiting (empty = no Redis) |
 | `CLICKHOUSE_HOST` | `localhost` | Event analytics (empty = no ClickHouse) |
 | `FORENSIC_BACKEND` | `memory` | Forensic store: `memory` \| `filesystem` \| `s3` (else `domains.compliance.forensic.backend` of `admina.yaml`) |
 | `FORENSIC_BASE_DIR` | *(empty)* | Directory of the `filesystem` store (else `domains.compliance.forensic.base_dir`) |
+| `ADMINA_EU_AI_ACT_ASSESSMENTS_PATH` | *(empty)* | JSON file keeping the last 100 EU AI Act assessments across restarts (empty: in memory only; the compose files set it on the `compliance-data` volume) |
 | `ADMINA_FORENSIC_FAIL_MODE` | `open` | A forensic record that cannot be written: `open` (logged, request served) \| `closed` (`503`, not forwarded) |
 | `LOG_LEVEL` | `INFO` | Logging verbosity |
 | `ADMINA_LOG_FORMAT` | `text` | Log output: `text` \| `json` |
@@ -1917,6 +2015,14 @@ 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"]}'
 
+# EU AI Act assessment of a limited-risk system (recorded as NOT_APPLICABLE)
+curl -X POST http://localhost:8080/api/compliance/gap-analysis \
+  -H "Content-Type: application/json" \
+  -d '{"risk_category":"limited","system_name":"Helpdesk bot"}'
+
+# The most recent EU AI Act assessment (404 without one)
+curl http://localhost:8080/api/compliance/gap-analysis/latest
+
 # Dashboard governance score
 curl http://localhost:8080/api/dashboard/score
 ```

{admina-0.14.2 → admina-0.15.0}/admina/__init__.py

@@ -23,7 +23,7 @@ from __future__ import annotations
 
 from admina.sdk import ComplianceKit, GovernedAgent, GovernedData, GovernedModel
 
-__version__ = "0.14.2"
+__version__ = "0.15.0"
 
 __all__ = [
     "__version__",