insa-its 3.0.0
Open-core multi-LLM communication monitoring, hallucination detection & deciphering for agent systems
Requires Python: >=3.8

# InsAIts - The Security Layer for Multi-Agent AI

**Detect, intervene, and audit AI-to-AI communication in real-time.**

[![PyPI version](https://badge.fury.io/py/insa-its.svg)](https://pypi.org/project/insa-its/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Tests](https://img.shields.io/badge/tests-139%20passing-brightgreen.svg)]()

---

## The Problem

When AI agents communicate with each other, things go wrong silently:

- **Hallucination propagation** - One agent fabricates a fact. The next treats it as truth. By agent 6, the error is buried under layers of confident responses.
- **Semantic drift** - Meaning shifts gradually across messages. By the end of a pipeline, the output has diverged from the original intent.
- **Fabricated sources** - Agents invent citations, DOIs, and URLs. In multi-agent systems, phantom citations pass between agents as established fact.
- **Silent contradictions** - Agent A says $1,000. Agent B says $5,000. No human is watching the AI-to-AI channel.

**In AI-to-human communication, we notice. In AI-to-AI? It's invisible.**

InsAIts makes it visible -- and acts on it.

---

## What It Does

InsAIts is a lightweight Python SDK that monitors AI-to-AI communication, detects 16 types of anomalies, and actively responds: quarantining dangerous messages, rerouting to backup agents, and escalating to human review.

```python
from insa_its import insAItsMonitor

monitor = insAItsMonitor()

# Monitor any AI-to-AI message
result = monitor.send_message(
    text=agent_response,
    sender_id="OrderBot",
    receiver_id="InventoryBot",
    llm_id="gpt-4o"
)

# V3: Structured result with programmatic decision-making
if result["monitor_result"].should_halt():
    # Critical anomaly -- quarantine + escalate to human
    outcome = monitor.intervene(message, result["monitor_result"])
elif result["monitor_result"].should_alert():
    # High severity -- log warning, optionally reroute
    pass
```

**Three lines to integrate. Full visibility. Active protection. Complete audit trail.**

All processing happens **locally** - your data never leaves your machine.

---

## Install

```bash
pip install insa-its
```

For local embeddings (recommended):
```bash
pip install insa-its[full]
```

---

## What It Detects

16 anomaly types across 5 categories:

| Category | Anomaly | What It Catches | Severity |
|----------|---------|-----------------|----------|
| **Hallucination** | FACT_CONTRADICTION | Agent A vs Agent B disagree on facts | Critical |
| | PHANTOM_CITATION | Fabricated URLs, DOIs, arxiv IDs | High |
| | UNGROUNDED_CLAIM | Response doesn't match source documents | Medium |
| | CONFIDENCE_DECAY | Agent certainty erodes: "certain" -> "maybe" | Medium |
| | CONFIDENCE_FLIP_FLOP | Agent alternates certain/uncertain | Medium |
| **Semantic (V3)** | SEMANTIC_DRIFT | Meaning shifts over conversation (EWMA + cosine) | High |
| | HALLUCINATION_CHAIN | Speculation promoted to "fact" across messages | Critical |
| | JARGON_DRIFT | Undefined acronyms flooding the conversation | Medium |
| **Communication** | SHORTHAND_EMERGENCE | "Process order" becomes "PO" | High |
| | CONTEXT_LOSS | Topic suddenly changes mid-conversation | High |
| | CROSS_LLM_JARGON | Made-up acronyms: "QXRT", "ZPMF" | High |
| | ANCHOR_DRIFT | Response diverges from user's question | High |
| **Model** | LLM_FINGERPRINT_MISMATCH | GPT-4 response looks like GPT-3.5 | Medium |
| | LOW_CONFIDENCE | Excessive hedging: "maybe", "perhaps" | Medium |
| **Compliance** | LINEAGE_DRIFT | Semantic divergence from parent message | Medium |
| | CHAIN_TAMPERING | Hash chain integrity violation | Critical |

---

## V3: Active Intervention

V3 transforms InsAIts from a monitoring tool into a **communication security platform**. It doesn't just detect -- it responds.

### Intervention Engine

```python
# Enable interventions
engine = monitor.enable_interventions()

# Register human-in-the-loop for critical anomalies
def review_critical(message, result, context):
    # Your review logic -- Slack notification, dashboard alert, etc.
    return True  # Allow delivery, or False to quarantine

engine.register_hitl_callback(review_critical)

# Register agent rerouting for high-severity issues
engine.register_reroute("risky_agent", "backup_agent")

# Process intervention
outcome = monitor.intervene(message, result["monitor_result"])
# {"action": "quarantined", "severity": "critical", "reason": "..."}
```

| Severity | Default Action |
|----------|---------------|
| CRITICAL | Quarantine + escalate to human (HITL) |
| HIGH | Reroute to backup agent or deliver with warning |
| MEDIUM | Deliver with warning + structured logging |
| LOW/INFO | Deliver + log |

### Circuit Breaker

Automatically blocks agents with high anomaly rates:

```python
# Built into send_message() -- automatic
result = monitor.send_message("text", "agent1", "agent2", "gpt-4o")
# If agent1's anomaly rate exceeds threshold: result = {"error": "circuit_open", ...}

# Manual inspection
state = monitor.get_circuit_breaker_state("agent1")
# {"state": "closed", "anomaly_rate": 0.15, "window_size": 20}
```

- Sliding window tracking (default: 20 messages per agent)
- State machine: CLOSED -> OPEN -> HALF_OPEN -> CLOSED
- Configurable threshold (default: 40% anomaly rate)
- Independent state per agent

### Tamper-Evident Audit Log

SHA-256 hash chain for regulatory compliance:

```python
# Enable audit logging
monitor.enable_audit("./audit_trail.jsonl")

# Messages are automatically logged (hashes only, never content)
# ...

# Verify integrity at any time
assert monitor.verify_audit_integrity()  # Detects any tampering
```

### Prometheus Metrics

```python
# Get Prometheus-formatted metrics for Grafana, Datadog, etc.
metrics_text = monitor.get_metrics()

# Metrics: insaits_messages_total, insaits_anomalies_total{severity="..."},
#          insaits_processing_duration_ms (histogram)
```

### System Readiness

```python
readiness = monitor.check_readiness()
# {"ready": True, "checks": {"license": {"status": "ok"}, ...}, "warnings": [], "errors": []}
```

---

## Hallucination Detection

Five independent detection subsystems:

```python
monitor = insAItsMonitor()
monitor.enable_fact_tracking(True)

# Cross-agent fact contradictions
monitor.send_message("The project costs 1000 dollars.", "agent_a", llm_id="gpt-4o")
result = monitor.send_message("The project costs 5000 dollars.", "agent_b", llm_id="claude-3.5")
# result["anomalies"] includes FACT_CONTRADICTION (critical)

# Phantom citation detection
citations = monitor.detect_phantom_citations(
    "According to Smith et al. (2030), see https://fake-journal.xyz/paper"
)
# citations["verdict"] = "likely_fabricated"

# Source grounding
monitor.set_source_documents(["Your reference docs..."], auto_check=True)
result = monitor.check_grounding("AI response to verify")
# result["grounded"] = True/False

# Confidence decay tracking
stats = monitor.get_confidence_stats(agent_id="agent_a")

# Full hallucination health report
summary = monitor.get_hallucination_summary()
```

| Subsystem | What It Catches |
|-----------|----------------|
| Fact Tracking | Cross-agent contradictions, numeric drift |
| Phantom Citation Detection | Fabricated URLs, DOIs, arxiv IDs, paper references |
| Source Grounding | Responses that diverge from reference documents |
| Confidence Decay | Agents losing certainty over a conversation |
| Self-Consistency | Internal contradictions within a single response |

---

## Forensic Chain Tracing

Trace any anomaly back to its root cause:

```python
trace = monitor.trace_root(anomaly)
print(trace["summary"])
# "Jargon 'XYZTERM' first appeared in message from agent_a (gpt-4o)
#  at step 3 of 7. Propagated through 4 subsequent messages."

# ASCII visualization
print(monitor.visualize_chain(anomaly, include_text=True))
```

---

## Integrations

### LangChain (V3 Updated)
```python
from insa_its.integrations import LangChainMonitor

monitor = LangChainMonitor()
monitored_chain = monitor.wrap_chain(your_chain, "MyAgent",
    workflow_id="order-123",      # V3: correlation ID for tracing
    halt_on_critical=True          # V3: auto-halt on critical anomalies
)
```

### CrewAI
```python
from insa_its.integrations import CrewAIMonitor
monitor = CrewAIMonitor()
monitored_crew = monitor.wrap_crew(your_crew)
```

### LangGraph
```python
from insa_its.integrations import LangGraphMonitor
monitor = LangGraphMonitor()
monitored_graph = monitor.wrap_graph(your_graph)
```

### Slack Alerts
```python
from insa_its.integrations import SlackNotifier
slack = SlackNotifier(webhook_url="https://hooks.slack.com/...")
slack.send_alert(anomaly)
```

### Exports
```python
from insa_its.integrations import NotionExporter, AirtableExporter
notion = NotionExporter(token="secret_xxx", database_id="db_123")
notion.export_anomalies(anomalies)
```

---

## Anchor-Aware Detection

Reduce false positives by setting the user's query as context:

```python
monitor.set_anchor("Explain quantum computing")
# Now "QUBIT", "QPU" won't trigger jargon alerts -- they're relevant to the query
```

---

## Domain Dictionaries

```python
# Load domain-specific terms to reduce false positives
monitor.load_domain("finance")     # EBITDA, WACC, DCF, etc.
monitor.load_domain("kubernetes")  # K8S, HPA, CI/CD, etc.
# Available: finance, healthcare, kubernetes, machine_learning, devops, quantum

# Custom dictionaries
monitor.export_dictionary("my_team_terms.json")
monitor.import_dictionary("shared_terms.json", merge=True)
```

---

## Open-Core Model

The core SDK is **Apache 2.0 open source**. Premium features ship with `pip install insa-its`.

| Feature | License | Status |
|---------|---------|--------|
| All 16 anomaly detectors | Apache 2.0 | Open |
| Hallucination detection (5 subsystems) | Apache 2.0 | Open |
| V3: Circuit breaker, interventions, audit, metrics | Apache 2.0 | Open |
| V3: Semantic drift, hallucination chain, jargon drift | Apache 2.0 | Open |
| Forensic chain tracing + visualization | Apache 2.0 | Open |
| All integrations (LangChain, CrewAI, LangGraph, Slack, Notion, Airtable) | Apache 2.0 | Open |
| Terminal dashboard | Apache 2.0 | Open |
| Local embeddings + Ollama | Apache 2.0 | Open |
| **AI Lineage Oracle** (compliance) | Proprietary | Premium |
| **Edge/Hybrid Swarm Router** | Proprietary | Premium |
| **Decipher Engine** (AI-to-Human translation) | Proprietary | Premium |
| **Adaptive jargon dictionaries** | Proprietary | Premium |
| **Advanced shorthand/context-loss detection** | Proprietary | Premium |
| **Anchor drift forensics** | Proprietary | Premium |

**Both open-source and premium features are included when you `pip install insa-its`.**
The public GitHub repo contains the Apache 2.0 open-source core only.

---

## Architecture

```
Your Multi-Agent System                    InsAIts V3 Security Layer
         |                                          |
         |-- user query -----> set_anchor() ------> |
         |-- source docs ----> set_source_documents() |
         |                                          |
         |-- message --------> Circuit Breaker ---> |
         |                     (is agent blocked?)   |
         |                                          |-- Embedding generation (local)
         |                                          |-- Pattern analysis
         |                                          |-- Hallucination suite (5 subsystems)
         |                                          |-- Semantic drift (EWMA + cosine)
         |                                          |-- Hallucination chain (promotion detection)
         |                                          |-- Jargon drift (vocabulary analysis)
         |                                          |
         |                                          |-- Build MonitorResult
         |                                          |-- Circuit breaker state update
         |                                          |-- Structured logging + metrics
         |                                          |-- Audit log (SHA-256 hash chain)
         |                                          |
         |<-- MonitorResult (should_halt/alert) ----|
         |                                          |
         |-- intervene() ---> Intervention Engine   |
         |                    CRITICAL: quarantine   |
         |                    HIGH: reroute/warn     |
         |                    MEDIUM: warn + log     |
         |                    LOW: deliver + log     |
```

**Privacy First:**
- All detection and intervention runs locally
- No message content sent to cloud
- Audit logs store hashes, never raw content
- API keys hashed before storage
- GDPR-ready

---

## Pricing

| Tier | What You Get | Price |
|------|--------------|-------|
| **Free** | 100 msgs/day, all open-source features | **$0** |
| **Pro** | Unlimited messages, cloud features, premium detectors | **Contact us** |
| **Enterprise** | Everything + compliance exports, SLA, self-hosted | **Custom** |

> Free tier works without an API key. Just `pip install insa-its` and start monitoring.

### 100 FREE LIFETIME Keys

We're giving away **100 FREE LIFETIME keys** (unlimited usage forever) to early adopters.

**How to claim:** Email **info@yuyai.pro** with your use case (1-2 sentences). First 100 get lifetime access.

---

## Use Cases

| Industry | Problem Solved |
|----------|----------------|
| **E-Commerce** | Order bots losing context mid-transaction |
| **Customer Service** | Support agents developing incomprehensible shorthand |
| **Finance** | Analysis pipelines hallucinating metrics, contradicting numbers |
| **Healthcare** | Critical multi-agent systems where errors have consequences |
| **Research** | Ensuring scientific integrity, catching fabricated citations |
| **Legal** | AI-generated documents with phantom references |

---

## Documentation

| Resource | Link |
|----------|------|
| Installation Guide | [installation_guide.md](installation_guide.md) |
| API Reference | [insaitsapi-production.up.railway.app/docs](https://insaitsapi-production.up.railway.app/docs) |
| Privacy Policy | [PRIVACY_POLICY.md](../PRIVACY_POLICY.md) |
| Terms of Service | [TERMS_OF_SERVICE.md](TERMS_OF_SERVICE.md) |

---

## Support

- **Email:** info@yuyai.pro
- **GitHub Issues:** [Report a bug](https://github.com/Nomadu27/InsAIts/issues)
- **API Status:** [insaitsapi-production.up.railway.app](https://insaitsapi-production.up.railway.app)

---

## License

**Open-Core Model:**
- Core SDK: [Apache License 2.0](LICENSE) - free to use, modify, and distribute
- Premium features (`insa_its/premium/`): Proprietary - included via `pip install insa-its`

---

<p align="center">
<strong>InsAIts V3.0 - Making Multi-Agent AI Trustworthy, Auditable, and Secure</strong><br>
<em>16 anomaly types. Active intervention. Tamper-evident audit. Circuit breaker. Prometheus metrics.</em><br><br>
<strong>100 FREE LIFETIME keys for early adopters: info@yuyai.pro</strong>
</p>