Il 20 maggio 2026 viene pubblicato Admina 0.9.1, primo rilascio pubblico del framework. La release è pre-1.0: l’API è feature-complete e in esercizio, ma può ancora evolvere in base ai riscontri dei primi utilizzatori prima del congelamento 1.0. Licenza Apache 2.0, repository github.com/admina-org/admina.

Cos’è

Admina è un framework per lo sviluppo di applicazioni AI governate. Un singolo install fornisce cinque componenti coordinati: un SDK, un proxy trasparente, un sistema a plugin, una CLI e una dashboard. Ogni componente applica le stesse regole di governance, sia in-process (via SDK) sia in rete (via proxy). L’integrazione con applicazioni esistenti non richiede modifiche di codice quando si opera in modalità proxy.

Architettura — quattro domini di governance

Le regole sono organizzate in quattro domini applicati bidirezionalmente (su richieste in uscita e risposte in entrata):

  • Agent Security — firewall anti-injection (fast path a 15 regex + scoring euristico) e loop breaker (similarità coseno TF-IDF)
  • Data Sovereignty — redazione PII (spaCy NER + regex per email, telefono, codici fiscali, carte di credito, IBAN, IP), enforcement di zone di residenza, classificazione dei dati
  • Compliance — classificazione del rischio secondo EU AI Act (Articolo 6), gap analysis contro gli Articoli 9–15, forensic black box (catena di hash SHA-256 con MinIO), span nativi OpenTelemetry
  • AI Infrastructure — opt-in: LLMEngine (Ollama / vLLM con auto-rilevamento GPU), RAGPipeline (ChromaDB / Milvus con chunking configurabile), WebUI (container Open WebUI con auth integrata, OIDC o LDAP)

Motore ibrido e overhead misurato

Il motore è ibrido Python + Rust tramite PyO3. I percorsi sensibili alla latenza (regex anti-injection, redazione PII, hashing forense) sono in Rust. L’overhead mediano misurato sulla pipeline completa a quattro domini è 6.25 µs (P95 7.04 µs, P99 7.29 µs). La suite di benchmark è in scripts/benchmark.py, con ambiente Docker riproducibile in docker-compose.benchmark.yml.

SDK

Quattro primitive, con interfaccia async e sincrona:

  • GovernedModel — wrap di un LLM con redazione PII automatica, audit trail ed emissione eventi; adapter Ollama e OpenAI inclusi
  • GovernedData — enforcement di residenza, classificazione e scrubbing PII su ogni ingest e query
  • GovernedAgent — wrap di agenti MCP / tool-calling con firewall, rilevamento loop e layer PII in-process
  • ComplianceKit — classificazione del rischio EU AI Act, gap analysis e generazione di report strutturati

Import di primo livello: from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit. Marker py.typed e type hint completi.

Proxy

Proxy FastAPI sulla porta 8080 con passthrough JSON-RPC 2.0 su POST /mcp e ispezione bidirezionale. API REST: POST /api/v1/validate, POST /api/v1/audit, POST /api/compliance/classify, GET /health, GET /governance/status, GET /api/stats, GET /api/forensic/verify. Rate limiting su Redis, session tracking, middleware CORS. Le porte dei servizi interni (ClickHouse, Redis) sono vincolate a 127.0.0.1.

Sistema a plugin

Nove interfacce con discovery via entry-point e registrazione manuale: BaseModelAdapter, BaseDataConnector, BaseGovernanceGuard, BaseComplianceTemplate, BaseTransportAdapter, BaseForensicStore, BaseAuthProvider, BasePIIEngine, BaseAlertChannel. Implementazioni di riferimento incluse per Ollama, OpenAI, ChromaDB, filesystem, MCP, HTTP/REST, MinIO, API key, spaCy + regex, log, webhook, template EU AI Act. È disponibile un plugin opzionale GuardrailsAI per rilevamento di linguaggio tossico, jailbreak, bias e PII, con inferenza esclusivamente locale.

CLI

  • admina init <progetto> — genera admina.yaml, docker-compose.yml ed esempi di codice agent
  • admina dev — avvia l’intero stack di governance via Docker Compose con monitoring live dello stato
  • admina plugin list | install | create — gestione del ciclo di vita dei plugin
  • admina doctor — diagnostica dell’ambiente (Python, motore Rust, discovery plugin, validità configurazione, raggiungibilità infrastruttura)

Dashboard

Single-page React in tempo reale sulla porta 3000. Include: Admina Score (composito runtime 0–100), feed eventi live via WebSocket, vista di gap sul compliance EU AI Act, mappa di sovranità dei dati, stato dei modelli. Widget dedicato di adeguatezza OISG (Open / Intelligent / Secure / Governed): mappa 2×2, punteggio totale e checklist a 20 criteri, collocato in una sezione “Instance Configuration” che distingue la valutazione statica delle capacità dalle metriche di runtime. Endpoint: /api/dashboard/score, /feed, /compliance, /sovereignty, /infra, /models, /oisg. Reverse proxy nginx che instrada /api/* al container del proxy. L’hash di commit è iniettato al build time per tracciabilità di versione.

Integrazioni

  • LangChain — AdminaCallbackHandler governa ogni chiamata LLM e invocazione di tool in-process
  • CrewAI — admina_step_callback e admina_task_callback per governance multi-agent
  • n8n — pacchetto nodi community n8n-nodes-admina con AdminaGovern, AdminaAudit, AdminaDashboard
  • OpenClaw — skill admina-governance che instrada le azioni degli agent attraverso il proxy prima dell’esecuzione
  • Cheshire Cat AI — tre hook Python (agent_fast_reply, before_cat_sends_message, before_cat_recalls_memories) con setup sidecar

Tooling e qualità

Ambiente gestito con uv (uv sync --group dev) e uv.lock per risoluzione deterministica delle dipendenze. Python 3.11+ (pinnato via .python-version). ruff per lint e format, bandit per security lint, safety per scan di vulnerabilità delle dipendenze. pytest con copertura minima al 70%. GitHub Actions per CI (lint, test, coverage, security scan) e workflow di release con build di wheel multi-piattaforma (Linux x86_64 / aarch64, macOS x86_64 / arm64) e pubblicazione automatica del pacchetto al tag.

Installazione

Per lo stack completo con dashboard e infrastruttura via Docker:

git clone https://github.com/admina-org/admina.git
cd admina
./scripts/bootstrap-secrets.sh
docker compose up --build

Dashboard su http://localhost:3000, API docs su http://localhost:8080/docs.