ICHYRA — Engine + ITA + Governança (README unificado)

BACKEND CANÔNICO DO PILOTO. Piloto de 100 casos ao vivo (recall 100%, FPR 0%), Judge Groq com failover Ollama, jobs assíncronos. O ichyra-engine está arquivado como referência técnica.

ECOSSISTEMA ICHYRA: src/ichyra (ITA vectorial R_transform = S_d × P × V_inv + Lotus Defense 4 camadas) + ichyra-engine (FastAPI Zero Trust, pgvector, OIDC, observabilidade) + app/governance (32 princípios) + paper_ita.md + auditoria 0 achados. Ver CHANGELOG.md.

Stack

• Core: src/ichyra/core.py:16 IchyraITA, src/ichyra/embeddings.py:4 EmbeddingService (BAAI/bge-base-en-v1.5 configurável EMBEDDING_MODEL env, fallback hashlib)
• Engine: FastAPI 0.110 + SQLAlchemy + pgvector Vector(384) + cosine_distance (app/services/ichyra_core.py:22), JWT OIDC RS256 app/auth/dependencies.py:19, slowapi, structlog, bleach, prometheus-fastapi-instrumentator
• Governança: risk 0-4 app/governance/risk_classifier.py:1, checkpoint 10p checkpoint.py:1, orquestrador orchestrator.py:12, kill switch kill_switch.py:1, audit 13 campos audit.py:1
• Deploy: docker-compose.yml:11 pgvector/pgvector:pg16 + healthcheck + prometheus/grafana (profile monitoring), alembic/versions/001_pgvector.py, Makefile make init

Arquitetura unificada

USER -> AUTH (OIDC/JWT) -> AI GATEWAY -> INPUT SECURITY (Security Architect)
    -> LOTUS One Vehicle (stripping) -> ITA evaluate (Karmic Residue 0.20)
    -> POLICY ENGINE -> TOOL PERMISSION (TTL 15min, segregação) -> OUTPUT DLP -> AUDIT -> Immunity Vector
    + Orquestrador -> Motor Políticas (porteiro) -> Kill Switch middleware

Instalação

pip install "ichyra[all]"  # langchain, llama-index, pgvector, prometheus, bleach
# ou dev:
pip install -e . -r requirements.txt
# ou engine:
pip install -r requirements.txt

Quick Start (ITA puro)

from ichyra import IchyraITA
ita = IchyraITA()  # EMBEDDING_MODEL env
res = ita.evaluate(current_context="...", proposed_action="...", feedback_history=[{"context":"...","action":"...","severity":-0.9}])
if res.magnitude > 0.4: print("bloqueado", res.magnitude)

Quick Start com LangChain / LlamaIndex / CrewAI

from ichyra.integrations.langchain import IchyraLangChainHandler
handler = IchyraLangChainHandler(feedback_history=hist)
# ChatOpenAI(callbacks=[handler])
from ichyra.integrations.llama_index import IchyraLlamaIndexGuard
guard = IchyraLlamaIndexGuard(feedback_history=hist)
guard.filter(query, response)
from ichyra.integrations.crewai import IchyraCrewAIGuard
crew = IchyraCrewAIGuard(feedback_history=hist)  # severity negativa = violação
safe_tool = crew.guard_tool(minha_tool)  # bloqueia tool perigosa
veredito = crew.check(task=tarefa, output=resposta)  # + remédio se bloquear

Como rodar (engine)

make init  # gera .env com openssl rand -hex 32
docker compose up --build  # api:8000, db pgvector, redis
# ou local:
uvicorn app.main:app --reload
# monitoring:
docker compose --profile monitoring up
# health: /health, /ready, /metrics, /v1/governance/prompt (auth)
# painel executivo: /dashboard (só leitura, agregados, sem PII)

Testes, benchmark e carga

pytest tests -q  # 49 testes
python benchmarks/benchmark_100.py  # BGE real: FPR 43.3% sem judge em thr=0.85 (ver BENCHMARK_RESULT.md; FPR 0% só com judge)
python benchmarks/benchmark_100.py --judge-real "BAAI/bge-base-en-v1.5"  # com juiz (LLM_PROVIDER + LLM_API_KEY)
py -3.13 scripts/check_judge.py  # diz se o juiz está ligado ou o que falta
py -3.13 scripts/oidc_harness.py  # OIDC real 6/6 (S-01/S-09)
# carga (exige Docker + k6): .\scripts\k6_local.ps1  # mata zumbis, sobe tudo, roda, limpa

Piloto comercial

Ver PROPOSTA_PILOTO.md (R$ 12 mil, 30 dias, critérios medidos).

Auditoria

docs/security-audit/relatorio-auditoria-seguranca.pdf v3 0 achados (era 8). gitleaks.yml bloqueia CHANGEME_GERE_AQUI.

Licença

MIT