Da utilizzare per incorporare componenti open source e di terze parti nei tuoi progetti, oppure come base per 
un nuovo progetto open source con l'obiettivo di spostare l'economia dello sviluppo di dApp verso 
la sua comunità di manutentori e lontano da intermediari che cercano rendite.

#### Componenti personalizzati

Sono disponibili i seguenti componenti personalizzati per integrare funzionalità di marketplace nei tuoi 
Workflows:

- [Log Snag](https://github.com/PipedreamHQ/pipedream/components/blob/master/pipedream/logsnag/README.md): 
  Tieni traccia facilmente degli eventi del tuo workflow e ricevi notifiche su desktop, dispositivo mobile o smartwatch.
- [OneSignal](https://github.com/PipedreamHQ/pipedream/blob/master/components/onesignal/README.md) / 
  [Twilio SendGrid](https://github.com/PipedreamHQ/pipedream/blob/master/components/sendgrid/README.md): 
  Invia email e notifiche push ai tuoi utenti.```python
import os
from tealtiger import TealOpenAI
client = TealOpenAI(api_key=os.environ["OPENAI_API_KEY"], guardrails={"prompt_injection": True})
print(client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello!"}]).security.decision)

Prossimo: [full Quick Start](#-quick-start) e [esempi](https://github.com/agentguard-ai/tealtiger/blob/HEAD/examples).

---

## 🔭 observe() — Strumentazione Zero-Config (v1.4)

Una riga aggiunge il monitoraggio dei costi, la registrazione di audit, il rilevamento di PII e le baseline comportamentali a qualsiasi client LLM. Nessun file di configurazione, nessuna definizione di policy.```typescript
import { observe, freeze } from 'tealtiger';
const client = observe(new OpenAI());  // done — all calls are now instrumented
console.log(client.getCost());         // { totalCost: 0.0023, requestCount: 1, ... }

**Cosa ottieni automaticamente:** monitoraggio dei costi per richiesta su 12 provider, log di audit strutturato con ID di correlazione, baseline comportamentale (P50/P95/P99), rilevamento PII in modalità REPORT_ONLY e un interruttore di arresto immediato tramite `freeze()`. Overhead inferiore a 5ms per chiamata.

Vedi [examples/observe-quickstart.ts](https://github.com/agentguard-ai/tealtiger/blob/HEAD/examples/observe-quickstart.ts) e [examples/observe_quickstart.py](https://github.com/agentguard-ai/tealtiger/blob/HEAD/examples/observe_quickstart.py).

---

---

## 📊 Dashboard di Governance (v1.4)

Visibilità in tempo reale sulla tua flotta di agenti AI — postura di sicurezza, governance dei costi e avvisi comportamentali in un'unica vista.

<div align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12842/41f95973c706522c5b907a5d7d96565247adff159a2de9a15c45087ae8dd1351.png" alt="Dashboard di Governance TealTiger" width="900">
</div>



**Cosa vedi a colpo d'occhio:**
- **Riga KPI** — Richieste totali, costo, rifiuti di governance, consumo di budget con indicatori colorati
- **Velocità di costo e previsione del budget** — Tendenze del tasso di consumo e proiezione di esaurimento
- **Pipeline di difesa** — Flusso di valutazione della sicurezza in 3 fasi con tassi di cortocircuito e latenza per fase
- **Avvisi Canary** — Rilevamento di deriva comportamentale con stato di congelamento dell'agente e percentuali di deviazione
- **Matrice degli agenti** — Tabella dello stato della flotta (attivo/inattivo/congelato) con metriche delle richieste per agente
- **Risparmio sui costi** — Raccomandazioni di ottimizzazione classificate per impatto
- **Routing dei modelli** — Routing da sorgente a destinazione con risparmi per richiesta
- **Governance del protocollo** — Schede policy ENFORCE/MONITOR/REPORT_ONLY con conteggi di rifiuto

Ogni pannello viene recuperato indipendentemente con isolamento dei guasti — il fallimento di un widget non si propaga mai agli altri.

Esegui localmente: `cd dashboard/api && npm run dev` poi `cd dashboard/web && npm run dev` (API sulla :3100, UI sulla :3000)

### Percorso di divulgazione progressiva

| Livello | Punto di ingresso | Cosa ottieni |
|-------|-------------|--------------|
| 0 | `observe(client)` | Monitoraggio dei costi, trail di audit, rilevamento PII, baseline comportamentale, interruttore di arresto |
| 1 | + configurazione guardrails | Iniezione di prompt, moderazione dei contenuti, rilevamento segreti |
| 2 | + policy TealEngine | ENFORCE/MONITOR/REPORT_ONLY per regola, decisioni deterministiche |
| 3 | + flussi di lavoro TealFlow | Ereditarietà della governance a livello di organizzazione, YAML dichiarativo |



## Cos'è TealTiger?

TealTiger è un SDK open-source che fornisce **governance deterministica** per agenti AI. Applica policy di sicurezza, monitora i costi e produce prove strutturate — tutto a runtime, senza necessità di infrastruttura.

> **Cerchi il codice sorgente?** Questo è il repository hub. Il codice sorgente dell'SDK si trova nei repository specifici per linguaggio:
> - **SDK TypeScript**: [tealtiger-typescript-prod](https://github.com/agentguard-ai/tealtiger-typescript-prod)
> - **SDK Python**: [tealtiger-python-prod](https://github.com/agentguard-ai/tealtiger-python-prod)
>
> Oppure clona questo repository con i sottomoduli: `git clone --recurse-submodules https://github.com/agentguard-ai/tealtiger.git`

A differenza dei filtri di sicurezza probabilistici, TealTiger utilizza **valutazione deterministica delle policy**: stesso input + stessa policy = stessa decisione, ogni volta. Ogni verdetto di governance è ricostruibile, tracciabile fino all'umano che ha creato la policy ed esportabile come prova strutturata (SARIF, JUnit XML, JSON).

**Principio chiave:** La governance dovrebbe essere una proprietà ingegneristica incorporata nel runtime — non un documento revisionato dopo i fatti.

---

## 🚀 Avvio Rapido

### TypeScript```bash
npm install tealtiger

### Python```bash
pip install tealtiger

---

## ✨ Funzionalità

### 🛡️ Guardrail di Sicurezza
- **Rilevamento PII** — Rileva e oscura automaticamente le informazioni sensibili
- **Prevenzione di Prompt Injection** — Blocca tentativi malevoli di iniezione di prompt
- **Moderazione dei Contenuti** — Filtra contenuti tossici, dannosi o inappropriati
- **Rilevamento Segreti** — 500+ pattern in 9 categorie con punteggio di confidenza
- **Regole Personalizzate** — Definisci le tue politiche di sicurezza

### 💰 Governance dei Costi
- **Applicazione del Budget** — Limiti rigidi per richiesta, sessione e giorno
- **Monitoraggio dei Costi** — Monitoraggio in tempo reale su tutti i provider
- **Avvisi di Costo** — Notifiche a soglie configurabili
- **Interruttori di Sicurezza** — Previene automaticamente cicli di costo incontrollati

### 🔌 12 Provider LLM
- **OpenAI** — GPT-4, GPT-4o, GPT-3.5
- **Anthropic** — Claude 3.5, Claude 3
- **Google Gemini** — Supporto multimodale
- **AWS Bedrock** — Claude, Titan, Jurassic, Command, Llama
- **Azure OpenAI** — Routing basato sul deployment
- **Cohere** — Chat, RAG, embeddings
- **Mistral AI** — Residenza dati europea
- **DeepSeek** — Modelli di ragionamento efficienti in termini di costi
- **Groq** — Inferenza a latenza ultra-bassa
- **Together AI** — Hosting di modelli open-source
- **HuggingFace TGI** — Inferenza auto-ospitata
- **xAI (Grok)** — Conoscenza in tempo reale

### 🔌 Adattatori di Piattaforma
- **AWS Bedrock Agents** — Adattatore nativo per guardrail
- **AWS AgentCore** — Plugin di governance pre/post azione
- **Azure AI Agent Service** — Middleware per pipeline di chiamata strumenti

### 🏗️ Architettura di Governance
- **Valutazione Deterministica delle Policy** — Nessun LLM nel percorso di governance
- **Evidenza Strutturata** — Ogni decisione produce un record ricostruibile
- **Prova Crittografica** — Alberi di Merkle + timestamp RFC 3161 (TealProof)
- **Identità Non Umana (NHI)** — Ciclo di vita dell'agente, applicazione dell'ambito, Zero Standing Privilege
- **Regole FREEZE** — Interruttori di emergenza immutabili con rilevamento di manomissioni
- **ID di Correlazione** — Tracciabilità end-to-end lungo la catena decisionale
- **Tracciabilità delle Policy** — Ogni verdetto riconduce all'autore umano della policy
- **OWASP Agentic Top 10** — Pacchetto di policy a configurazione zero che copre tutti e 10 i rischi ASI

---

## 🗺️ Copertura di Governance

| Dimensione | Cosa fa | Modulo |
|-----------|---------|--------|
| 🛡️ **Sicurezza** | Rilevamento segreti (500+ pattern), prompt injection, PII, moderazione contenuti, normalizzazione Unicode, rilevamento output codificato | `TealSecrets` `TealGuard` |
| 🔑 **Identità** | Ciclo di vita dell'Identità Non Umana, applicazione ambito, Zero Standing Privilege, attestazione agente | `TealEngine (NHI)` |
| ⚡ **Affidabilità** | Interruttori di sicurezza, budget di ripetizione, catene di fallback, degradazione deterministica | `TealCircuit` `TealReliability` |
| 🧠 **Memoria** | Provenienza scrittura, rilevamento iniezione istruzioni, prevenzione esfiltrazione, applicazione ambito | `TealMemory` |
| 💰 **Costo** | Soffitti di proprietà della governance, rilevamento anomalie, budget di token di ragionamento, attribuzione per agente | `TealMonitor` |
| 📋 **Evidenza** | Ricevute crittografiche (Merkle + RFC 3161), esportazione SARIF, span OTel, integrazione SIEM | `TealProof` `TealAudit` |
| ⚙️ **Policy** | Regole FREEZE, modalità PLAN_ONLY, bundle hot-swap, anti-manomissione, livelli di automazione | `TealEngine` |
| 🔄 **Flusso di Lavoro** | Flussi di lavoro di governance YAML dichiarativi, ereditarietà a livello organizzativo, applicazione di base | `TealFlow` |
| 📊 **Deriva** | Rilevamento deriva comportamentale, basi statistiche, regressione output modello | `TealDrift` |
| ⏱️ **Temporale** | TTL sessione, periodi di raffreddamento, restrizioni orarie | `TealTemporal` |
| 🔍 **Registro** | Monitoraggio deriva definizione MCP, scansione descrizione strumenti, lista bianca composizione adattatori | `TealRegistry` |
| 🧠 **Classificazione** | Inferenza ML ONNX locale (≤20ms), modalità ensemble, combinazione regex+ML | `TealClassifier` |

> **Principio di progettazione:** Nessun LLM nel percorso di governance. Stesso input + stessa policy = stessa decisione, ogni volta.

---

## 📦 SDK

| Lingua | Codice Sorgente | Pacchetto | Installazione |
|----------|------------|---------|---------|
| TypeScript | [tealtiger-typescript-prod](https://github.com/agentguard-ai/tealtiger-typescript-prod) | [npm](https://www.npmjs.com/package/tealtiger) | `npm install tealtiger` |
| Python | [tealtiger-python-prod](https://github.com/agentguard-ai/tealtiger-python-prod) | [PyPI](https://pypi.org/project/tealtiger/) | `pip install tealtiger` |

### 🔌 Adattatori per Framework

| Framework | Pacchetto | Installazione |
|-----------|---------|---------|
| LangChain | [langchain-tealtiger](https://github.com/agentguard-ai/tealtiger/tree/main/packages/langchain-tealtiger) | `pip install langchain-tealtiger` |
| Vercel AI SDK | [tealtiger-ai-sdk](https://github.com/agentguard-ai/tealtiger/tree/main/packages/tealtiger-ai-sdk) | `npm install tealtiger-ai-sdk` |
| PydanticAI | [pydanticai-tealtiger](https://github.com/agentguard-ai/tealtiger/tree/main/packages/pydanticai-tealtiger) | `pip install pydanticai-tealtiger` |
| Haystack | [haystack-tealtiger](https://github.com/agentguard-ai/tealtiger/tree/main/packages/haystack-tealtiger) | `pip install haystack-tealtiger` |
| CAMEL-AI | [camelai-tealtiger](https://github.com/agentguard-ai/tealtiger/tree/main/packages/camelai-tealtiger) | `pip install camelai-tealtiger` |

### 🔗 Integrazioni di Infrastruttura

| Piattaforma | Cosa fornisce | Installazione |
|----------|-----------------|---------|
| [Dakera](https://github.com/Dakera-AI/dakera-py) | Backend di stato di governance persistente (archiviazione costi, ricevute decisioni, catene di delega tramite KG) | `pip install dakera[tealtiger]` | [Docs](https://dakera.ai/integrations/tealtiger) |
| [AG2 Beta](https://github.com/ag2ai/ag2) | Estensione middleware di governance per agenti AG2 Beta | `pip install ag2-tealtiger` |
| [Portkey Gateway](https://github.com/Portkey-AI/gateway) | Guardrail webhook per Portkey AI Gateway | [Esempio](https://github.com/agentguard-ai/tealtiger/tree/main/examples/portkey-webhook-guardrail) |
| [Daytona](https://github.com/daytonaio/daytona) | Governance pre-esecuzione per esecuzione codice in sandbox | [Esempio](https://github.com/agentguard-ai/tealtiger/tree/main/examples/daytona-governed-sandbox) |

---

## 📚 Documentazione

- [Perché il tuo agente AI ha bisogno di un budget — governance dei costi per app LLM](https://github.com/agentguard-ai/tealtiger/blob/HEAD/docs/blog/cost-governance-for-llm-apps.md)
- [OWASP Agentic Top 10 — difese pratiche con TealTiger](https://github.com/agentguard-ai/tealtiger/blob/HEAD/docs/blog/owasp-agentic-top-10-defenses.md)
- [Guida Rapida](#-quick-start)
- [Guardrail di Sicurezza](#️-security-guardrails)
- [Governance dei Costi](#-cost-governance)
- [Configurazione Provider](#-7-llm-providers)
- [FAQ](https://github.com/agentguard-ai/tealtiger/blob/HEAD/docs/faq.md)
- [Perché TealTiger?](https://github.com/agentguard-ai/tealtiger/blob/HEAD/docs/why-tealtiger.md)
- [Matrice di Parità Funzionale Cross-SDK](https://github.com/agentguard-ai/tealtiger/blob/HEAD/docs/cross-sdk-feature-parity-matrix.md)
- [Indici del Store Eventi di Governance](https://github.com/agentguard-ai/tealtiger/blob/HEAD/docs/governance-event-store-indexes.md)
- [Riferimento Codice di Errore](https://github.com/agentguard-ai/tealtiger/blob/HEAD/docs/error-code-reference.md)
- [Risoluzione dei Problemi](https://github.com/agentguard-ai/tealtiger/blob/HEAD/docs/troubleshooting.md)
- [Guida ai Contributi](https://github.com/agentguard-ai/tealtiger/blob/HEAD/CONTRIBUTING.md)
- [Politica di Sicurezza](https://github.com/agentguard-ai/tealtiger/blob/HEAD/SECURITY.md)
- [Codice di Condotta](https://github.com/agentguard-ai/tealtiger/blob/HEAD/CODE_OF_CONDUCT.md)
- [Roadmap](https://github.com/agentguard-ai/tealtiger/blob/HEAD/ROADMAP.md)

### Badge

Usa il badge TealTiger per mostrare che un progetto è governato da politiche di sicurezza e costi deterministiche degli agenti.

Badge chiaro:

[![TealTiger](https://img.shields.io/badge/Protected_by-TealTiger-00A9FF?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTIgMkwyIDd2NWMwIDUgNCA5IDggMTBzOC01IDgtMTBWOWwtMTAtNXoiIGZpbGw9IiNmZmYiLz48cGF0aCBkPSJNMTIgNEw0IDh2M2MwIDQgMy4yIDYuNSA4IDcuNHYtMTF6IiBmaWxsPSIjMDBBOUZGIi8+PC9zdmc+)](https://tealtiger.io)

[![TealTiger](https://img.shields.io/badge/Protected_by-TealTiger-00A9FF?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTIgMkwyIDd2NWMwIDUgNCA5IDggMTBzOC01IDgtMTBWOWwtMTAtNXoiIGZpbGw9IiMwMDBiMTkiLz48cGF0aCBkPSJNMTIgNEw0IDh2M2MwIDQgMy4yIDYuNSA4IDcuNHYtMTF6IiBmaWxsPSIjMDBBOUZGIi8+PC9zdmc+)](https://tealtiger.io)```md
[![Governed by TealTiger](https://raw.githubusercontent.com/agentguard-ai/tealtiger/main/assets/badges/governed-by-tealtiger.svg)](https://github.com/agentguard-ai/tealtiger)

### Python Hugging Face TGI Quickstart

Use `examples/python/huggingface_tgi_quickstart.py` per provare il provider protetto Hugging Face Text Generation Inference dall'SDK Python.```bash
export HF_API_TOKEN="your-hugging-face-token"
export HF_TGI_ENDPOINT="https://your-endpoint.endpoints.huggingface.cloud"
export HF_TGI_MODEL="meta-llama/Meta-Llama-3.1-8B-Instruct"

python examples/python/huggingface_tgi_quickstart.py

Per le policy YAML, configura la mappatura dello schema YAML del tuo editor in modo che i file di policy come `tealtiger-policy.yml` puntino a `./schemas/tealtiger-policy.schema.json`.

### Convalidare i File di Policy

Usa lo script di convalida delle policy per verificare un file JSON di policy TealTiger prima di utilizzarlo in ambienti CI/CD o di governance runtime:```bash
npm install
npx ts-node scripts/validate-policy.ts ./my-policy.json

Il caricatore carica
[`schemas/tealtiger-policy.schema.json`](https://github.com/agentguard-ai/tealtiger/blob/HEAD/schemas/tealtiger-policy.schema.json),
stampa gli errori di validazione dello schema, esce con `0` quando la policy è valida, ed esce
con `1` quando la policy è non valida.

---

## 🐯 Costruisci con noi — Programma per primi contributori

TealTiger è open source e stiamo cercando primi contributori per dare forma al futuro della governance degli agenti IA.

### Su cosa puoi lavorare

| Area | Esempi | Difficoltà |
|------|--------|------------|
| 🔍 Rilevamento dei segreti | Nuovi pattern di rilevamento, categorie personalizzate | 🟢 Principiante |
| 📝 Documentazione | Guide, esempi, documentazione API, correzioni di errori di battitura | 🟢 Principiante |
| 🧪 Test | Test unitari, test basati su proprietà, test di integrazione | 🟡 Intermedio |
| 🔌 Integrazioni | Middleware LangChain, CrewAI, AG2, LlamaIndex | 🟡 Intermedio |
| 💾 Adattatori di memoria | Adattatori per Redis, Pinecone, Weaviate, ChromaDB | 🟡 Intermedio |
| 🔄 Modelli CI/CD | Jenkins, Azure Pipelines, Bitbucket Pipelines | 🟡 Intermedio |
| 🏗️ Moduli principali | Motore di governance, esportazione delle evidenze, valutazione delle policy | 🔴 Avanzato |

### Cosa ottengono i primi contributori

- 🏆 **Nominato in CONTRIBUTORS.md** e nelle note di rilascio
- 🎖️ **Badge "Founding Contributor"** — primi 25 PR merged ottengono un riconoscimento permanente
- 📣 **Ringraziamenti sui canali social di TealTiger** (LinkedIn, X, Dev.to)
- 🔑 **Accesso anticipato** alle prossime funzionalità di governance prima del rilascio pubblico
- 💬 **Accesso diretto** al team principale tramite GitHub Discussions
- 📝 **Opportunità di co-autore** per articoli tecnici sul blog

### Per iniziare```bash
# 1. Star this repo (it helps!)

# 2. Fork and clone the SDK you want to contribute to:
# TypeScript SDK:
git clone https://github.com/agentguard-ai/tealtiger-typescript-prod.git
# Python SDK:
git clone https://github.com/agentguard-ai/tealtiger-python-prod.git

# 3. Pick a "good first issue"
# https://github.com/agentguard-ai/tealtiger/issues?q=label%3A%22good+first+issue%22

# 4. Submit a PR
# 5. Join the team 🐯