ichyra-guard 0.7.0__tar.gz

ichyra_guard-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tai and Marcio Santos de Lima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ichyra_guard-0.7.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: ichyra-guard
+Version: 0.7.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

ichyra_guard-0.7.0/README.md

@@ -0,0 +1,85 @@
+![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

ichyra_guard-0.7.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ichyra-guard"
+version = "0.7.0"
+description = "Ichyra Guard — ITA vectorial + Lotus + Zero Trust + Governança 32 (avaliação ética auditável para LLMs)"
+readme = "README.md"
+authors = [
+  { name = "Tai and Marcio Santos de Lima", email = "mark.iodelima@gmail.com" },
+]
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["ai", "ethics", "llm", "guardrails", "alignment"]
+dependencies = [
+    "sentence-transformers>=2.2.0",
+    "numpy>=1.21.0"
+]
+requires-python = ">=3.9"
+
+[project.optional-dependencies]
+langchain = ["langchain>=0.1.0", "langchain-core>=0.1.0"]
+llama-index = ["llama-index>=0.10.0"]
+all = ["langchain>=0.1.0", "llama-index>=0.10.0", "pgvector>=0.3.6", "prometheus-client>=0.20.0", "bleach>=6.0.0"]
+dev = ["pytest>=7.0", "httpx>=0.27.0"]
+
+[project.urls]
+"Homepage" = "https://github.com/Lotuvia-Governanca/ichyra-projeto"
+"Bug Tracker" = "https://github.com/Lotuvia-Governanca/ichyra-projeto/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

ichyra_guard-0.7.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ichyra_guard-0.7.0/src/ichyra/__init__.py

@@ -0,0 +1,22 @@
+from .core import IchyraITA, CorrectionResult
+from .judge import LLMJudge
+from .lotus import OneVehicleStripper, ImmutableAxiomVerifier, KarmicResidueCalculator, PoisonIntoMedicine
+
+try:
+    from .integrations.langchain import IchyraLangChainHandler
+    from .integrations.llama_index import IchyraLlamaIndexGuard
+except Exception:
+    IchyraLangChainHandler = None
+    IchyraLlamaIndexGuard = None
+
+__all__ = [
+    "IchyraITA",
+    "CorrectionResult",
+    "LLMJudge",
+    "OneVehicleStripper",
+    "ImmutableAxiomVerifier",
+    "KarmicResidueCalculator",
+    "PoisonIntoMedicine",
+    "IchyraLangChainHandler",
+    "IchyraLlamaIndexGuard",
+]

ichyra_guard-0.7.0/src/ichyra/core.py

@@ -0,0 +1,164 @@
+import numpy as np
+import datetime, os
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass
+from .embeddings import EmbeddingService
+from .lotus import KarmicResidueCalculator
+
+@dataclass
+class CorrectionResult:
+    magnitude: float
+    detected: bool
+    details: Dict[str, Any]
+
+# Pontos de operação medidos em sweep REAL sem judge (ver BENCHMARK_RESULT.md).
+# Cosseno absoluto é frágil sob anisotropia (baseline BGE ~0.8+); estes defaults
+# calibrados valem até haver scoring relativo (margem/rank, requer histórico
+# multi-âncora — ainda não implementado).
+CALIBRATED_THRESHOLDS = {
+    "bge-base": 0.85,  # sweep v2 real: recall 100%, FPR 43.3%
+}
+
+def calibrated_default(model_name: str) -> float:
+    low = (model_name or "").lower()
+    for key, thr in CALIBRATED_THRESHOLDS.items():
+        if key in low:
+            return thr
+    return 0.55
+
+# Corte violação vs âncora safe: severity > -0.4 é âncora safe.
+# Default -0.5 cai no lado violação (conservador).
+SAFE_SEVERITY_ABOVE = -0.4
+
+class IchyraITA:
+    def __init__(self, embedding_model: str = None):
+        env_model = os.getenv("EMBEDDING_MODEL", "")
+        self.embedding_model_name = embedding_model or env_model or "BAAI/bge-base-en-v1.5"
+        self.embedder = EmbeddingService(self.embedding_model_name)
+        # threshold via env ou ponto calibrado por modelo (sweep real)
+        self.default_threshold = float(os.getenv("ITA_THRESHOLD") or calibrated_default(self.embedding_model_name))
+
+    def evaluate(self,
+                 current_context: str,
+                 proposed_action: str,
+                 feedback_history: List[Dict[str, Any]],
+                 threshold: float = None,
+                 use_llm_judge: bool = None,
+                 relative: bool = None,
+                 margin_threshold: float = None) -> CorrectionResult:
+        if threshold is None:
+            threshold = self.default_threshold
+        if use_llm_judge is None:
+            use_llm_judge = os.getenv("LLM_JUDGE_ENABLED", "false").lower() == "true"
+        if margin_threshold is None:
+            margin_threshold = float(os.getenv("ITA_MARGIN_THRESHOLD", "0.008"))
+
+        if not feedback_history:
+            return CorrectionResult(magnitude=0.0, detected=False, details={})
+
+        v_curr = self.embedder.encode(current_context, proposed_action)
+        now = datetime.datetime.now(datetime.timezone.utc)
+
+        # Coleta (s_d, p, record, is_safe) com decaimento kármico assintótico (Lotus L3).
+        scored = []
+        karmic_calc = KarmicResidueCalculator()
+        
+        # Contagem de reincidências de violações graves no histórico
+        grave_violations_count = sum(1 for r in feedback_history if abs(float(r.get("severity", -0.5))) >= 0.8)
+
+        for record in feedback_history:
+            # Cache do embedding histórico para não recalcular N vezes
+            if "_cached_vec" not in record:
+                record["_cached_vec"] = self.embedder.encode(record["context"], record["action"])
+            v_orig = record["_cached_vec"]
+            similarity = float(np.dot(v_curr, v_orig))
+            s_d = similarity
+            p = abs(float(record.get("severity", -0.5)))
+            
+            if "timestamp" in record and isinstance(record["timestamp"], datetime.datetime):
+                delta_days = (now - record["timestamp"]).days
+                decay_factor = karmic_calc.compute_decay(
+                    delta_days=delta_days,
+                    severity=p,
+                    recurrence_count=grave_violations_count
+                )
+                s_d = similarity * decay_factor
+            
+            is_safe = float(record.get("severity", -0.5)) > SAFE_SEVERITY_ABOVE
+            scored.append((s_d, p, record, is_safe))
+
+        # Modo relativo: auto quando há safe anchors; legado caso contrário.
+        if relative is None:
+            relative = any(s[3] for s in scored)
+        if relative:
+            return self._evaluate_relative(current_context, proposed_action, scored,
+                                           margin_threshold, use_llm_judge)
+
+        max_magnitude = 0.0
+        best_match = None
+        for (s_d, p, record, _is_safe) in scored:
+            if s_d > threshold:
+                p = abs(float(record.get("severity", -0.5)))
+                magnitude = s_d * p
+                # LLM Judge segunda checagem: chama LLM para confirmar se é falso-positivo
+                # Em produção BGE, judge filtra FP semântico fino (ex: negar vs oferecer ajuda)
+                if use_llm_judge:
+                    llm_confirm = self._llm_judge(current_context, proposed_action, record)
+                    if llm_confirm is False:  # LLM diz que é falso-positivo
+                        continue  # descarta este match — não conta como violação
+                    elif llm_confirm is True:
+                        pass  # confirma violação
+                if magnitude > max_magnitude:
+                    max_magnitude = magnitude
+                    best_match = {
+                        "historical_context": record["context"],
+                        "historical_action": record["action"],
+                        "similarity": s_d,
+                        "base_severity": p,
+                        "embedding_model": self.embedding_model_name,
+                        "llm_judge_used": use_llm_judge,
+                    }
+
+        # Se LLM judge reduziu todos, detected pode ser False mesmo com similaridade alta
+        return CorrectionResult(
+            magnitude=max_magnitude,
+            detected=(max_magnitude > 0.4),  # threshold final de magnitude (calibrado)
+            details=best_match or {}
+        )
+
+    def _evaluate_relative(self, current_context: str, proposed_action: str,
+                           scored, margin_threshold: float,
+                           use_llm_judge: bool) -> CorrectionResult:
+        """Decisão por margem: mais perto de violação conhecida que de safe conhecido."""
+        viol = [(s, p, r) for (s, p, r, safe) in scored if not safe]
+        safe = [(s, p, r) for (s, p, r, safe) in scored if safe]
+        if not viol:
+            return CorrectionResult(magnitude=0.0, detected=False,
+                                    details={"mode": "relative", "reason": "no-violation-anchors"})
+        s_v, p_v, rec_v = max(viol, key=lambda t: t[0])
+        if safe:
+            s_s, _, rec_s = max(safe, key=lambda t: t[0])
+        else:
+            s_s, rec_s = 0.0, None
+        margin = s_v - s_s
+        base_details = {"mode": "relative", "margin": margin, "s_viol": s_v, "s_safe": s_s,
+                        "threshold": margin_threshold, "embedding_model": self.embedding_model_name,
+                        "llm_judge_used": use_llm_judge,
+                        "historical_context": rec_v["context"], "historical_action": rec_v["action"]}
+        if margin <= margin_threshold:
+            return CorrectionResult(magnitude=0.0, detected=False, details=base_details)
+        if use_llm_judge:
+            llm_confirm = self._llm_judge(current_context, proposed_action, rec_v)
+            if llm_confirm is False:  # judge diz falso-positivo
+                d = dict(base_details); d["judge"] = "fp-filtered"
+                return CorrectionResult(magnitude=0.0, detected=False, details=d)
+        return CorrectionResult(magnitude=max(0.0, margin) * p_v, detected=True, details=base_details)
+
+    def _llm_judge(self, current_context: str, proposed_action: str, record: Dict[str,Any]) -> Optional[bool]:
+        """Avalia via LLMJudge multi-provedor (OpenAI, Claude, Ollama local)"""
+        try:
+            from .judge import LLMJudge
+            judge_instance = LLMJudge()
+            return judge_instance.judge(current_context, proposed_action, record)
+        except Exception:
+            return None

ichyra_guard-0.7.0/src/ichyra/embeddings.py

@@ -0,0 +1,54 @@
+import os, numpy as np
+
+class EmbeddingService:
+    """
+    Handles encoding with configurable production model.
+    Env EMBEDDING_MODEL controla: all-MiniLM-L6-v2 (rápido, FP 94%), BAAI/bge-base-en-v1.5 (produção, recomendado),
+    BAAI/bge-large-en-v1.5 (máx precisão, 1024 dims), intfloat/e5-large-v2.
+    Fallback gracioso se modelo não baixado.
+    """
+    def __init__(self, model_name: str = None):
+        env_model = os.getenv("EMBEDDING_MODEL", "")
+        self.model_name = model_name or env_model or "BAAI/bge-base-en-v1.5"
+        self._model = None
+        self._load_error = None
+        # SKIP_DOWNLOAD para CI/benchmark rápido — usa fallback sem baixar
+        if os.getenv("SKIP_DOWNLOAD","").lower() == "true":
+            self._load_error = "SKIP_DOWNLOAD=true"
+            return
+        try:
+            from sentence_transformers import SentenceTransformer
+            self._model = SentenceTransformer(self.model_name, device="cpu")
+        except Exception as e:
+            self._load_error = str(e)
+            self._model = None
+
+    def encode(self, context: str, action: str) -> np.ndarray:
+        text = f"contexto: {context}\nação: {action}"
+        if self._model is not None:
+            try:
+                # BGE requer prefixo "Represent this sentence for searching relevant passages: " para query; simplificamos
+                embedding = self._model.encode(text, convert_to_numpy=True, normalize_embeddings=True)
+                # já normalizado se normalize_embeddings=True
+                norm = np.linalg.norm(embedding)
+                if norm > 0 and abs(norm - 1.0) > 1e-3:
+                    embedding = embedding / norm
+                return embedding
+            except Exception:
+                pass
+        # Fallback determinístico (para CI sem download)
+        import hashlib
+        h = hashlib.sha256(text.encode()).digest()
+        vec = np.array([b/255 for b in h[:16]], dtype=np.float32)
+        # expande para 384 para compat
+        vec = np.tile(vec, 24)[:384]
+        norm = np.linalg.norm(vec)
+        return vec / norm if norm > 0 else vec
+
+    @property
+    def is_real(self) -> bool:
+        return self._model is not None
+
+    @property
+    def info(self) -> dict:
+        return {"model": self.model_name, "real": self.is_real, "error": self._load_error}

ichyra_guard-0.7.0/src/ichyra/integrations/__init__.py

@@ -0,0 +1,5 @@
+from .langchain import IchyraLangChainHandler
+from .llama_index import IchyraLlamaIndexGuard
+from .crewai import IchyraCrewAIGuard
+
+__all__ = ["IchyraLangChainHandler", "IchyraLlamaIndexGuard", "IchyraCrewAIGuard"]

ichyra_guard-0.7.0/src/ichyra/integrations/crewai.py

@@ -0,0 +1,76 @@
+"""
+CrewAI integration — ICHYRA como porteiro de ferramentas e saídas.
+Uso:
+  from ichyra.integrations.crewai import IchyraCrewAIGuard
+  guard = IchyraCrewAIGuard(threshold=0.85)
+  # 1. Envolve qualquer tool do CrewAI (2 linhas):
+  safe_tool = guard.guard_tool(minha_tool)
+  # 2. Ou checa a saída do agente antes de entregar:
+  veredito = guard.check(task="resumir tickets", output=text)
+  # veredito = {"blocked": bool, "magnitude": float, "remedy": str|None}
+Delegação pura para IchyraITA — sem duplicar lógica, sem depender do
+pacote crewai instalado (duck-typing: aceita qualquer callable).
+"""
+from typing import List, Dict, Any, Optional, Callable
+
+
+class IchyraCrewAIGuard:
+    """
+    Porteiro ICHYRA para agentes CrewAI (ou qualquer framework de agentes).
+    Lazy: só importa IchyraITA no primeiro uso.
+    """
+
+    def __init__(self, feedback_history: List[Dict[str, Any]] = None,
+                 threshold: float = 0.85, use_llm_judge: bool = None,
+                 embedding_model: str = None):
+        self.feedback_history = feedback_history or []
+        self.threshold = threshold
+        self.use_llm_judge = use_llm_judge
+        self.embedding_model = embedding_model
+        self._ita = None
+
+    @property
+    def ita(self):
+        if self._ita is None:
+            from ..core import IchyraITA
+            self._ita = IchyraITA(
+                embedding_model=self.embedding_model) if self.embedding_model else IchyraITA()
+        return self._ita
+
+    def check(self, task: str, output: str) -> Dict[str, Any]:
+        """Avalia a saída do agente contra a tarefa. Retorna veredito + remédio."""
+        res = self.ita.evaluate(
+            current_context=task, proposed_action=output,
+            feedback_history=self.feedback_history,
+            threshold=self.threshold, use_llm_judge=self.use_llm_judge)
+        remedy = None
+        if res.detected:
+            remedy = (f"[ICHYRA] magnitude {res.magnitude:.3f} acima do "
+                      f"limite {self.threshold}. Reavalie com empatia e "
+                      f"proteção antes de entregar.")
+        return {"blocked": res.detected, "magnitude": res.magnitude,
+                "details": res.details, "remedy": remedy}
+
+    def guard_tool(self, fn: Callable) -> Callable:
+        """Envolve uma tool: avalia os argumentos antes de executar."""
+        def wrapped(*args, **kwargs):
+            textual = " ".join([str(a) for a in args] +
+                               [f"{k}={v}" for k, v in kwargs.items()])
+            res = self.ita.evaluate(
+                current_context=f"tool:{getattr(fn, '__name__', 'tool')}",
+                proposed_action=textual,
+                feedback_history=self.feedback_history,
+                threshold=self.threshold, use_llm_judge=self.use_llm_judge)
+            if res.detected:
+                raise PermissionError(
+                    f"[ICHYRA] tool bloqueada (magnitude {res.magnitude:.3f})")
+            return fn(*args, **kwargs)
+        wrapped.__name__ = getattr(fn, "__name__", "guarded_tool")
+        wrapped.__doc__ = fn.__doc__
+        return wrapped
+
+    def add_feedback(self, context: str, action: str, severity: float, timestamp=None):
+        import datetime
+        self.feedback_history.append({
+            "context": context, "action": action, "severity": severity,
+            "timestamp": timestamp or datetime.datetime.now(datetime.timezone.utc)})

ichyra_guard-0.7.0/src/ichyra/integrations/langchain.py

@@ -0,0 +1,61 @@
+"""
+LangChain integration — ICHYRA as a callback / guardrail
+Uso:
+  from ichyra.integrations.langchain import IchyraLangChainHandler
+  handler = IchyraLangChainHandler(feedback_history=[...])
+  llm = ChatOpenAI(callbacks=[handler])  # ou chain com handler
+  # handler avalia cada LLM output e bloqueia se magnitude > threshold
+Delegação pura para IchyraITA — sem duplicar lógica.
+"""
+from typing import List, Dict, Any, Optional
+
+class IchyraLangChainHandler:
+    """
+    LangChain callback handler que usa ICHYRA ITA como porteiro.
+    Compatível com LangChain Core callbacks (on_llm_end).
+    Lazy: só importa IchyraITA quando chamado.
+    """
+    def __init__(self, feedback_history: List[Dict[str,Any]] = None, threshold: float = 0.55, use_llm_judge: bool = None, embedding_model: str = None):
+        self.feedback_history = feedback_history or []
+        self.threshold = threshold
+        self.use_llm_judge = use_llm_judge
+        self.embedding_model = embedding_model
+        self._ita = None
+
+    @property
+    def ita(self):
+        if self._ita is None:
+            from ..core import IchyraITA
+            self._ita = IchyraITA(embedding_model=self.embedding_model) if self.embedding_model else IchyraITA()
+        return self._ita
+
+    def evaluate(self, context: str, proposed_action: str) -> Dict[str,Any]:
+        res = self.ita.evaluate(current_context=context, proposed_action=proposed_action, feedback_history=self.feedback_history, threshold=self.threshold, use_llm_judge=self.use_llm_judge)
+        return {"magnitude": res.magnitude, "blocked": res.detected, "details": res.details}
+
+    # LangChain callback hook
+    def on_llm_end(self, response, **kwargs):
+        # response.generations[0][0].text
+        try:
+            text = response.generations[0][0].text if hasattr(response, "generations") else str(response)
+            context = kwargs.get("context", "")
+            res = self.evaluate(context, text)
+            if res["blocked"]:
+                # Em prod, levanta ou reescreve; aqui apenas anexa
+                response._ichyra_blocked = True
+                response._ichyra_magnitude = res["magnitude"]
+        except Exception:
+            pass
+
+    # Para Chains / Agents: avalia antes de tool
+    def on_tool_start(self, serialized, input_str, **kwargs):
+        # avalia se tool é de alto risco; usa Security Architect se disponível
+        pass
+
+    def add_feedback(self, context: str, action: str, severity: float, timestamp=None):
+        import datetime
+        self.feedback_history.append({"context": context, "action": action, "severity": severity, "timestamp": timestamp or datetime.datetime.now(datetime.timezone.utc)})
+
+    def to_react_prompt(self, magnitude: float) -> str:
+        # Poison into Medicine: prompt de auto-correção proporcional
+        return f"[ICHYRA] Correção vetorial R_transform magnitude {magnitude:.3f} detectada. Reavalie sua ação com empatia e proteção, integrando a sombra (Shadow Integration)."