Metadata-Version: 2.4
Name: ichyra-guard
Version: 0.8.0
Summary: Ichyra Guard — ITA vectorial + Lotus + Zero Trust + Governança 32 (avaliação ética auditável para LLMs)
Author-email: Tai and Marcio Santos de Lima <mark.iodelima@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Lotuvia-Governanca/ichyra-projeto
Project-URL: Bug Tracker, https://github.com/Lotuvia-Governanca/ichyra-projeto/issues
Keywords: ai,ethics,llm,guardrails,alignment
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: numpy>=1.21.0
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: llama-index
Requires-Dist: llama-index>=0.10.0; extra == "llama-index"
Provides-Extra: all
Requires-Dist: langchain>=0.1.0; extra == "all"
Requires-Dist: llama-index>=0.10.0; extra == "all"
Requires-Dist: pgvector>=0.3.6; extra == "all"
Requires-Dist: prometheus-client>=0.20.0; extra == "all"
Requires-Dist: bleach>=6.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Dynamic: license-file

![CI](https://github.com/markiolima30-coder/ichyra-ita/actions/workflows/ci.yml/badge.svg) ![Gitleaks](https://github.com/markiolima30-coder/ichyra-ita/actions/workflows/gitleaks.yml/badge.svg) ![Coverage](https://img.shields.io/badge/coverage-49%20tests-green) ![Version](https://img.shields.io/badge/version-0.6.2-blue)

# 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
```bash
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)
```python
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
```python
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)
```bash
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
```bash
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
