argus-debate-ai 3.1.0
ARGUS: Production-ready multi-agent AI debate framework with RAG, Bayesian reasoning, provenance tracking, 50+ tool integrations, OpenAPI REST generation, context caching/compression, and advanced LLM orchestration for scientific discovery, fact-checking, and evidence-based decision-making
License: MIT
Requires Python: >=3.11
Keywords: ai, artificial-intelligence, multi-agent, debate, reasoning, llm, gpt, claude, gemini, scientific-discovery, research, decision-making, fact-checking, verification, rag, retrieval-augmented-generation, embeddings, vector-search, knowledge-graph, bayesian-inference, argumentation, provenance, langchain-alternative, agent-framework, llm-framework, openai, anthropic, ollama, openapi, rest-api, context-caching, context-compression, tool-integrations, observability, mlops

# ARGUS

**Agentic Research & Governance Unified System**

*A debate-native, multi-agent AI framework for evidence-based reasoning with structured argumentation, decision-theoretic planning, and full provenance tracking.*

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/argus-debate-ai.svg)](https://pypi.org/project/argus-debate-ai/3.1.0/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Type Checking: mypy](https://img.shields.io/badge/type%20checking-mypy-blue.svg)](https://mypy.readthedocs.io/)
[![Tools: 50+](https://img.shields.io/badge/tools-50+-green.svg)](https://github.com/Ronit26Mehta/argus-ai-debate#tool-integrations-50)
[![LLM Providers: 27+](https://img.shields.io/badge/LLM%20providers-27+-purple.svg)](https://github.com/Ronit26Mehta/argus-ai-debate#llm-providers-27)

---

## Table of Contents

- [Overview](#overview)
- [Key Innovations](#key-innovations)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [LLM Providers](#llm-providers)
- [Tool Integrations (50+)](#tool-integrations-50)
- [OpenAPI REST Integration](#openapi-rest-integration)
- [Context Caching](#context-caching)
- [Context Compression](#context-compression)
- [Debate Visualization](#debate-visualization)
- [External Connectors](#external-connectors)
- [Visualization & Plotting](#visualization--plotting)
- [Argus Terminal (TUI)](#argus-terminal-tui)
- [Argus-Viz (Streamlit Sandbox)](#argus-viz-streamlit-sandbox)
- [CRUX Protocol](#crux-protocol)
- [Command Line Interface](#command-line-interface)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Core Components](#core-components)
- [Algorithms](#algorithms)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Testing](#testing)
- [Deployment](#deployment)
- [Contributing](#contributing)
- [License](#license)

---

## Overview

ARGUS implements **Research Debate Chain (RDC)** - a novel approach to AI reasoning that structures knowledge evaluation as multi-agent debates. Instead of single-pass inference, ARGUS orchestrates specialist agents that gather evidence, generate rebuttals, and render verdicts through Bayesian aggregation.

### Why ARGUS?

Traditional LLM applications suffer from:
- **Hallucination**: Models generate plausible but incorrect information
- **Overconfidence**: No calibrated uncertainty estimates
- **Opacity**: Black-box reasoning with no audit trail
- **Single-Point Failure**: One model, one perspective

ARGUS addresses these through:
- **Adversarial Debate**: Multiple agents challenge claims with evidence
- **Bayesian Aggregation**: Calibrated confidence through probability theory
- **Full Provenance**: Every claim traced to its source
- **Multi-Model Support**: Use different LLMs for different roles

---

## Key Innovations

### Conceptual Debate Graph (C-DAG)
A directed graph structure where propositions, evidence, and rebuttals are nodes with signed edges representing support/attack relationships. The graph enables:
- Structured argument representation
- Influence propagation via Bayesian updating
- Conflict detection and resolution
- Visual debugging and analysis

### Evidence-Directed Debate Orchestration (EDDO)
Algorithm for managing multi-round debates with configurable stopping criteria:
- Convergence detection (posterior stability)
- Maximum rounds enforcement
- Budget-based termination
- Information gain thresholds

### Value of Information Planning
Decision-theoretic experiment selection using Expected Information Gain (EIG):
- Prioritize high-value evidence gathering
- Optimal resource allocation under constraints
- Monte Carlo estimation of information value

### Full Provenance Tracking
PROV-O compatible ledger with hash-chain integrity:
- W3C standard compliance
- Cryptographic attestations
- Complete audit trails
- Tamper detection

---

## Features

### Multi-Agent Debate System

| Agent | Role | Capabilities |
|-------|------|--------------|
| **Moderator** | Orchestration | Creates debate agendas, manages rounds, evaluates stopping criteria, breaks ties |
| **Specialist** | Evidence Gathering | Domain-specific research, hybrid retrieval, source quality assessment |
| **Refuter** | Challenge Generation | Counter-evidence, methodological critiques, logical fallacy detection |
| **Jury** | Verdict Rendering | Bayesian aggregation, confidence calibration, label assignment |

### Conceptual Debate Graph (C-DAG)

**Node Types:**
| Type | Description | Attributes |
|------|-------------|------------|
| `Proposition` | Main claims under evaluation | text, prior, domain, status |
| `Evidence` | Supporting/attacking information | polarity, confidence, source, type |
| `Rebuttal` | Challenges to evidence | target_id, strength, rebuttal_type |
| `Finding` | Intermediate conclusions | derived_from, confidence |
| `Assumption` | Underlying premises | explicit, challenged |

**Edge Types:**
| Type | Polarity | Description |
|------|----------|-------------|
| `SUPPORTS` | +1 | Evidence supporting a proposition |
| `ATTACKS` | -1 | Evidence challenging a proposition |
| `REBUTS` | -1 | Rebuttal targeting evidence |
| `REFINES` | 0 | Clarification or specification |

**Propagation:** Log-odds Bayesian belief updating across the graph with configurable decay and damping.

### Hybrid Retrieval System

```
┌─────────────────────────────────────────────────────────────┐
│                    Hybrid Retriever                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │ BM25 Sparse │    │ FAISS Dense │    │ Cross-Encoder│     │
│  │  Retrieval  │ -> │  Retrieval  │ -> │  Reranking   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│        │                   │                  │              │
│        v                   v                  v              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         Reciprocal Rank Fusion (RRF)                │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

**Components:**
- **BM25 Sparse Retrieval**: Traditional keyword-based retrieval with TF-IDF scoring
- **FAISS Dense Retrieval**: Semantic vector search using sentence-transformers
- **Fusion Methods**: Weighted combination or Reciprocal Rank Fusion (RRF)
- **Cross-Encoder Reranking**: Neural reranking for precision (optional)

### Decision-Theoretic Planning

**Expected Information Gain (EIG):**
```python
# Estimate value of an experiment
planner = VoIPlanner(llm=llm, n_samples=1000)
ranked_actions = planner.rank_by_eig(experiments, current_belief)

# Select optimal action set under budget constraint
optimal_set = planner.select_under_budget(experiments, budget=100)
```

**Calibration:**
- Brier Score assessment
- Expected Calibration Error (ECE)
- Temperature scaling for confidence adjustment
- Histogram binning for reliability diagrams

### Provenance & Governance

**Event Types:**
| Event | Description |
|-------|-------------|
| `SESSION_START` | Debate session initialization |
| `PROPOSITION_ADDED` | New proposition registered |
| `EVIDENCE_ADDED` | Evidence attached to proposition |
| `REBUTTAL_ADDED` | Rebuttal targeting evidence |
| `VERDICT_RENDERED` | Jury verdict recorded |
| `SESSION_END` | Session completion |

**Integrity Features:**
- SHA-256 hash chain for tamper detection
- PROV-O compatible event model
- Cryptographic attestations for content
- Query API for filtering and analysis

---

## Installation

### From PyPI (Recommended)

```bash
pip install argus-debate-ai
```

### From Source (Development)

```bash
git clone https://github.com/argus-ai/argus.git
cd argus
pip install -e ".[dev]"
```

### Optional Dependencies

```bash
# All features including development tools
pip install argus-debate-ai[all]

# Individual extras
pip install argus-debate-ai[ollama]   # Ollama local LLM support
pip install argus-debate-ai[cohere]   # Cohere integration
pip install argus-debate-ai[mistral]  # Mistral integration
pip install argus-debate-ai[groq]     # Groq LPU inference
pip install argus-debate-ai[arxiv]    # arXiv connector
```

### System Requirements

| Requirement | Minimum | Recommended |
|-------------|---------|-------------|
| Python | 3.11+ | 3.12+ |
| RAM | 4 GB | 16 GB |
| Storage | 1 GB | 10 GB (with embeddings) |
| GPU | None | CUDA-compatible (for local embeddings) |

---

## Quick Start

### Basic Usage

```python
from argus import RDCOrchestrator, get_llm

# Initialize with any supported LLM
llm = get_llm("openai", model="gpt-4o")

# Run a debate on a proposition
orchestrator = RDCOrchestrator(llm=llm, max_rounds=5)
result = orchestrator.debate(
    "The new treatment reduces symptoms by more than 20%",
    prior=0.5,  # Start with 50/50 uncertainty
)

print(f"Verdict: {result.verdict.label}")
print(f"Posterior: {result.verdict.posterior:.3f}")
print(f"Evidence: {result.num_evidence} items")
print(f"Reasoning: {result.verdict.reasoning}")
```

### Building a Debate Graph Manually

```python
from argus import CDAG, Proposition, Evidence, EdgeType
from argus.cdag.nodes import EvidenceType
from argus.cdag.propagation import compute_posterior

# Create the graph
graph = CDAG(name="drug_efficacy_debate")

# Add the proposition to evaluate
prop = Proposition(
    text="Drug X is effective for treating condition Y",
    prior=0.5,
    domain="clinical",
)
graph.add_proposition(prop)

# Add supporting evidence
trial_evidence = Evidence(
    text="Phase 3 RCT showed 35% symptom reduction (n=500, p<0.001)",
    evidence_type=EvidenceType.EMPIRICAL,
    polarity=1,  # Supports
    confidence=0.9,
    relevance=0.95,
    quality=0.85,
)
graph.add_evidence(trial_evidence, prop.id, EdgeType.SUPPORTS)

# Add challenging evidence
side_effect = Evidence(
    text="15% of patients experienced adverse events",
    evidence_type=EvidenceType.EMPIRICAL,
    polarity=-1,  # Attacks
    confidence=0.8,
    relevance=0.7,
)
graph.add_evidence(side_effect, prop.id, EdgeType.ATTACKS)

# Add rebuttal to the challenge
rebuttal = Rebuttal(
    text="Adverse events were mild and resolved without intervention",
    target_id=side_effect.id,
    rebuttal_type="clarification",
    strength=0.7,
    confidence=0.85,
)
graph.add_rebuttal(rebuttal, side_effect.id)

# Compute Bayesian posterior
posterior = compute_posterior(graph, prop.id)
print(f"Posterior probability: {posterior:.3f}")
```

### Document Ingestion & Retrieval

```python
from argus import DocumentLoader, Chunker, EmbeddingGenerator
from argus.retrieval import HybridRetriever

# Load documents (supports PDF, TXT, HTML, Markdown, JSON)
loader = DocumentLoader()
doc = loader.load("research_paper.pdf")

# Chunk with overlap for context preservation
chunker = Chunker(chunk_size=512, chunk_overlap=50)
chunks = chunker.chunk(doc)

# Create hybrid retriever
retriever = HybridRetriever(
    embedding_model="all-MiniLM-L6-v2",
    lambda_param=0.7,  # Weight toward dense retrieval
    use_reranker=True,
)
retriever.index_chunks(chunks)

# Search with hybrid scoring
results = retriever.retrieve("treatment efficacy results", top_k=10)
for r in results:
    print(f"[{r.rank}] Score: {r.score:.3f} - {r.chunk.text[:100]}...")
```

### Multi-Agent Debate

```python
from argus import get_llm
from argus.agents import Moderator, Specialist, Refuter, Jury
from argus import CDAG, Proposition

# Initialize LLM (can use different models for different agents)
llm = get_llm("anthropic", model="claude-3-5-sonnet-20241022")

# Initialize agents
moderator = Moderator(llm)
specialist = Specialist(llm, domain="clinical")
refuter = Refuter(llm)
jury = Jury(llm)

# Create debate graph
graph = CDAG()
prop = Proposition(text="The intervention is cost-effective", prior=0.5)
graph.add_proposition(prop)

# Moderator creates agenda
agenda = moderator.create_agenda(graph, prop.id)

# Specialists gather evidence
evidence = specialist.gather_evidence(graph, prop.id)

# Refuter challenges evidence
rebuttals = refuter.generate_rebuttals(graph, prop.id)

# Jury renders verdict
verdict = jury.evaluate(graph, prop.id)
print(f"Verdict: {verdict.label} (posterior={verdict.posterior:.3f})")
print(f"Reasoning: {verdict.reasoning}")
```

---

## LLM Providers (27+)

ARGUS v3.1 supports **27+ LLM providers** through a unified interface. All providers implement the same `BaseLLM` interface for seamless interchangeability.

### Supported Providers

| Provider | Models | Features | API Key Env Variable |
|----------|--------|----------|---------------------|
| **OpenAI** | GPT-4o, GPT-4, o1 | Generate, Stream, Embed | `OPENAI_API_KEY` |
| **Anthropic** | Claude 3.5 Sonnet, Opus | Generate, Stream | `ANTHROPIC_API_KEY` |
| **Google** | Gemini 1.5 Pro/Flash | Generate, Stream, Embed | `GOOGLE_API_KEY` |
| **Ollama** | Llama 3.2, Mistral, Phi | Local deployment | N/A (local) |
| **Cohere** | Command R, R+ | Generate, Stream, Embed | `COHERE_API_KEY` |
| **Mistral** | Large, Small, Codestral | Generate, Stream, Embed | `MISTRAL_API_KEY` |
| **Groq** | Llama 3.1 70B (ultra-fast) | Generate, Stream | `GROQ_API_KEY` |
| **DeepSeek** | DeepSeek Chat, Coder | Generate, Stream | `DEEPSEEK_API_KEY` |
| **xAI** | Grok-beta | Generate, Stream | `XAI_API_KEY` |
| **Perplexity** | Sonar (search-grounded) | Generate, Stream | `PERPLEXITY_API_KEY` |
| **Together** | 100+ open models | Generate, Stream, Embed | `TOGETHER_API_KEY` |
| **Fireworks** | Fast inference | Generate, Stream | `FIREWORKS_API_KEY` |
| **NVIDIA** | NIM endpoints | Generate, Stream | `NVIDIA_API_KEY` |
| **Azure OpenAI** | GPT-4 on Azure | Generate, Stream, Embed | `AZURE_OPENAI_API_KEY` |
| **AWS Bedrock** | Claude, Llama on AWS | Generate, Stream | AWS credentials |
| **Vertex AI** | Gemini on GCP | Generate, Stream | GCP credentials |
| **+ 10 more** | See docs | Various | Various |


### Usage Examples

#### OpenAI
```python
from argus.core.llm import OpenAILLM

llm = OpenAILLM(model="gpt-4o")
response = llm.generate("Explain quantum computing")
print(response.content)
```

#### Anthropic
```python
from argus.core.llm import AnthropicLLM

llm = AnthropicLLM(model="claude-3-5-sonnet-20241022")
response = llm.generate(
    "Analyze this research methodology",
    system_prompt="You are a research methodology expert."
)
```

#### Google Gemini
```python
from argus.core.llm import GeminiLLM

llm = GeminiLLM(model="gemini-1.5-pro")
response = llm.generate("Summarize the key findings")

# Also supports embeddings
embeddings = llm.embed(["text to embed"])
```

#### Ollama (Local)
```python
from argus.core.llm import OllamaLLM

llm = OllamaLLM(model="llama3.1", host="http://localhost:11434")
response = llm.generate("What is the capital of France?")
```

#### Cohere
```python
from argus.core.llm import CohereLLM

llm = CohereLLM(model="command-r-plus")
response = llm.generate("Explain machine learning")

# Cohere embeddings with input types
embeddings = llm.embed(
    ["search query"],
    input_type="search_query"  # or "search_document"
)
```

#### Mistral
```python
from argus.core.llm import MistralLLM

llm = MistralLLM(model="mistral-large-latest")
response = llm.generate(
    "Write a Python function",
    temperature=0.3
)

# Streaming
for chunk in llm.stream("Tell me a story"):
    print(chunk, end="", flush=True)
```

#### Groq (Ultra-Fast Inference)
```python
from argus.core.llm import GroqLLM

llm = GroqLLM(model="llama-3.1-70b-versatile")
response = llm.generate("Explain photosynthesis")

# Groq also supports audio transcription
transcript = llm.transcribe("audio.wav")
```

### Provider Registry

```python
from argus.core.llm import get_llm, list_providers, register_provider

# List available providers
print(list_providers())
# ['openai', 'anthropic', 'gemini', 'ollama', 'cohere', 'mistral', 'groq']

# Get LLM by provider name
llm = get_llm("groq", model="llama-3.1-70b-versatile")

# Register custom provider
class MyCustomLLM(BaseLLM):
    # ... implementation
    pass

register_provider("custom", MyCustomLLM)
```

---

## Embedding Models (16+)

ARGUS v3.1 includes 16 embedding providers for semantic search and RAG applications.

### Available Providers

| Type | Providers |
|------|-----------|
| **Local (Free)** | SentenceTransformers, FastEmbed, Ollama |
| **Cloud APIs** | OpenAI, Cohere, HuggingFace, Voyage, Mistral, Google, Azure, Together, NVIDIA, Jina, Nomic, Bedrock, Fireworks |

### Quick Examples

```python
from argus.embeddings import get_embedding, list_embedding_providers

# List all 16 providers
print(list_embedding_providers())

# Local embedding (free, no API key)
embedder = get_embedding("sentence_transformers", model="all-MiniLM-L6-v2")
vectors = embedder.embed_documents(["Hello world", "Machine learning"])
print(f"Dimension: {len(vectors[0])}")  # 384

# Query embedding for search
query_vec = embedder.embed_query("What is AI?")

# OpenAI embeddings
embedder = get_embedding("openai", model="text-embedding-3-small")
vectors = embedder.embed_documents(["Doc 1", "Doc 2"])

# Cohere embeddings
embedder = get_embedding("cohere", model="embed-english-v3.0")
query_vec = embedder.embed_query("search query")  # Uses search_query input type
```

---

## Tool Integrations (50+)

ARGUS v3.1 includes **50+ pre-built tools** across 13 categories for comprehensive agent capabilities.

### Available Tools by Category

| Category | Tools | Description |
|----------|-------|-------------|
| **Search** | DuckDuckGo, Wikipedia, ArXiv, Tavily, Brave, Exa | Web and academic search |
| **Web** | Requests, WebScraper, JinaReader, YouTube | Web content access |
| **Productivity** | FileSystem, PythonREPL, Shell, GitHub, JSON | Core productivity |
| **Database** | SQL, Pandas | Data access and manipulation |
| **Finance** | YahooFinance, Weather | Financial and weather data |
| **AI Agents** | AgentMail, AgentOps, GoodMem, Freeplay | AI agent infrastructure |
| **Cloud** | BigQuery, PubSub, CloudTrace, VertexAI Search/RAG | Google Cloud services |
| **Vector DB** | Chroma, Pinecone, Qdrant, MongoDB | Vector databases |
| **Productivity (Extended)** | Asana, Jira, Confluence, Linear, Notion | Project management |
| **Communication** | Mailgun, Stripe, PayPal | Email and payments |
| **DevOps** | GitLab, Postman, Daytona, N8n | Development operations |
| **Media/AI** | ElevenLabs, Cartesia, HuggingFace | Media and AI platforms |
| **Observability** | Arize, Phoenix, Monocle, MLflow, W&B Weave | ML observability |

### Installation

```bash
# Core tools (search, web, productivity, database, finance)
pip install argus-debate-ai[tools]

# Extended tools (all 50+ integrations)
pip install argus-debate-ai[tools-extended]

# Or install all features
pip install argus-debate-ai[all]
```

### Quick Examples

```python
from argus.tools.integrations import (
    # Search
    DuckDuckGoTool, WikipediaTool, ArxivTool,
    # Productivity
    PythonReplTool, AsanaTool, NotionTool,
    # Cloud
    BigQueryTool, VertexAISearchTool,
    # Vector DB
    PineconeTool, QdrantTool,
    # Observability
    MLflowTool, WandBWeaveTool,
)

# Free web search
search = DuckDuckGoTool()
result = search(query="latest AI research 2024", max_results=5)
for r in result.data["results"]:
    print(f"- {r['title']}: {r['url']}")

# Wikipedia lookup
wiki = WikipediaTool()
result = wiki(query="Machine Learning", action="summary", sentences=3)
print(result.data["summary"])

# ArXiv paper search
arxiv = ArxivTool()
result = arxiv(query="transformer attention", max_results=5)
for paper in result.data["results"]:
    print(f"📄 {paper['title']}")

# Execute Python code
repl = PythonReplTool()
result = repl(code="print(sum([1,2,3,4,5]))")
print(result.data["output"])  # 15

# Asana task management
asana = AsanaTool()
result = asana(action="list_tasks", project_gid="your-project-id")

# Notion database query
notion = NotionTool()
result = notion(action="query_database", database_id="your-db-id")

# BigQuery data analysis
bq = BigQueryTool()
result = bq(action="query", query="SELECT * FROM dataset.table LIMIT 10")

# Pinecone vector search
pinecone = PineconeTool()
result = pinecone(action="query", vector=[0.1]*1536, top_k=5)

# MLflow experiment tracking
mlflow = MLflowTool()
result = mlflow(action="log_metric", run_id="run-123", key="accuracy", value=0.95)

# W&B Weave tracing
weave = WandBWeaveTool()
result = weave(action="log_call", call_data={"model": "gpt-4", "input": "Hello"})
```

### AI Agent Tools

Tools for AI agent infrastructure and orchestration:

```python
from argus.tools.integrations import AgentMailTool, AgentOpsTool, GoodMemTool, FreeplayTool

# AgentMail - Autonomous email handling
agentmail = AgentMailTool()
result = agentmail(action="create_inbox", name="support-agent")

# AgentOps - Agent observability
agentops = AgentOpsTool()
result = agentops(action="create_session", tags=["prod", "customer-support"])

# GoodMem - Long-term memory for agents
goodmem = GoodMemTool()
result = goodmem(action="create_memory", content="User prefers detailed explanations")

# Freeplay - LLM testing and evaluation
freeplay = FreeplayTool()
result = freeplay(action="run_test", prompt_id="prompt-123")
```

### Cloud Tools

Google Cloud Platform integrations:

```python
from argus.tools.integrations import (
    BigQueryTool, PubSubTool, CloudTraceTool,
    VertexAISearchTool, VertexAIRAGTool,
)

# BigQuery - Data warehouse
bq = BigQueryTool()
result = bq(action="query", query="SELECT * FROM analytics.events LIMIT 100")

# Pub/Sub - Messaging
pubsub = PubSubTool()
result = pubsub(action="publish", topic="events", message={"event": "user_signup"})

# Cloud Trace - Distributed tracing
trace = CloudTraceTool()
result = trace(action="create_span", name="process_request")

# Vertex AI Search - Enterprise search
search = VertexAISearchTool()
result = search(action="search", query="product documentation", data_store_id="my-store")

# Vertex AI RAG - Retrieval augmented generation
rag = VertexAIRAGTool()
result = rag(action="query", query="How do I configure X?", corpus_id="my-corpus")
```

### Vector Database Tools

Full CRUD operations for vector databases:

```python
from argus.tools.integrations import ChromaTool, PineconeTool, QdrantTool, MongoDBTool

# Chroma - Local vector DB
chroma = ChromaTool()
result = chroma(action="add", collection="docs", documents=["Hello world"], ids=["doc1"])

# Pinecone - Cloud vector DB
pinecone = PineconeTool()
result = pinecone(action="upsert", vectors=[{"id": "v1", "values": [0.1]*1536}])

# Qdrant - High-performance vector search
qdrant = QdrantTool()
result = qdrant(action="search", collection="embeddings", vector=[0.1]*384, limit=5)

# MongoDB - Document + vector search
mongodb = MongoDBTool()
result = mongodb(action="vector_search", collection="articles", vector=[0.1]*1536)
```

### Productivity Tools (Extended)

Project management and documentation tools:

```python
from argus.tools.integrations import AsanaTool, JiraTool, ConfluenceTool, LinearTool, NotionTool

# Asana - Project management
asana = AsanaTool()
result = asana(action="create_task", project_gid="123", name="Review PR", assignee="me")

# Jira - Issue tracking
jira = JiraTool()
result = jira(action="create_issue", project_key="PROJ", summary="Bug fix", issue_type="Bug")

# Confluence - Documentation
confluence = ConfluenceTool()
result = confluence(action="create_page", space_key="DOCS", title="API Guide", body="<p>...</p>")

# Linear - Engineering issues
linear = LinearTool()
result = linear(action="create_issue", team_id="team-123", title="Feature request")

# Notion - Knowledge management
notion = NotionTool()
result = notion(action="create_page", parent_id="page-123", title="Meeting Notes")
```

### Communication & Payment Tools

Email and payment processing:

```python
from argus.tools.integrations import MailgunTool, StripeTool, PayPalTool

# Mailgun - Email sending
mailgun = MailgunTool()
result = mailgun(action="send", to="user@example.com", subject="Welcome!", text="...")

# Stripe - Payments
stripe = StripeTool()
result = stripe(action="create_payment_intent", amount=2000, currency="usd")

# PayPal - Payments
paypal = PayPalTool()
result = paypal(action="create_order", amount="19.99", currency="USD")
```

### DevOps Tools

Development operations and automation:

```python
from argus.tools.integrations import GitLabTool, PostmanTool, DaytonaTool, N8nTool

# GitLab - Git operations
gitlab = GitLabTool()
result = gitlab(action="create_merge_request", project_id=123, source="feature", target="main")

# Postman - API testing
postman = PostmanTool()
result = postman(action="run_collection", collection_id="col-123")

# Daytona - Dev environments
daytona = DaytonaTool()
result = daytona(action="create_workspace", repository="https://github.com/org/repo")

# N8n - Workflow automation
n8n = N8nTool()
result = n8n(action="execute_workflow", workflow_id="wf-123")
```

### Media & AI Tools

Media generation and AI platforms:

```python
from argus.tools.integrations import ElevenLabsTool, CartesiaTool, HuggingFaceTool

# ElevenLabs - Text-to-speech
elevenlabs = ElevenLabsTool()
result = elevenlabs(action="text_to_speech", text="Hello world", voice_id="voice-123")

# Cartesia - Audio AI
cartesia = CartesiaTool()
result = cartesia(action="synthesize", text="Welcome to ARGUS", voice_id="voice-456")

# HuggingFace - ML models
huggingface = HuggingFaceTool()
result = huggingface(action="inference", model_id="gpt2", inputs="The future of AI is")
```

### Observability Tools

ML observability and monitoring:

```python
from argus.tools.integrations import ArizeTool, PhoenixTool, MonocleTool, MLflowTool, WandBWeaveTool

# Arize - ML observability
arize = ArizeTool()
result = arize(action="log_prediction", model_id="classifier-v1", prediction=0.85)

# Phoenix - LLM tracing
phoenix = PhoenixTool()
result = phoenix(action="log_span", name="llm_call", input="Query", output="Response")

# Monocle - GenAI tracing
monocle = MonocleTool()
result = monocle(action="start_trace", name="agent_workflow")

# MLflow - Experiment tracking
mlflow = MLflowTool()
result = mlflow(action="create_run", experiment_id="exp-123")

# W&B Weave - LLM evaluation
weave = WandBWeaveTool()
result = weave(action="create_dataset", name="eval-dataset", rows=[...])
```

### Tool Registry

```python
from argus.tools.integrations import (
    list_all_tools,
    list_tool_categories,
    get_tools_by_category,
    get_tool_count,
)

# List all 50+ tools
print(list_all_tools())

# List categories (13 categories)
print(list_tool_categories())
# ['search', 'web', 'productivity', 'database', 'finance', 'ai_agents', 
#  'cloud', 'vectordb', 'productivity_extended', 'communication', 
#  'devops', 'media_ai', 'observability']

# Get tools by category
observability_tools = get_tools_by_category("observability")
# [ArizeTool, PhoenixTool, MonocleTool, MLflowTool, WandBWeaveTool]

# Total count
print(f"Total tools: {get_tool_count()}")  # 50+
```

---

## OpenAPI REST Integration

ARGUS v3.1 includes a powerful OpenAPI module for automatically generating tools from REST API specifications.

### Features

- **OpenAPI v2 (Swagger) and v3 support**
- **Automatic client generation** from specs
- **Tool code generation** for agent integrations
- **Full authentication support** (API Key, Bearer, Basic, OAuth2)
- **Type-safe parameter handling**

### Installation

```bash
pip install argus-debate-ai[openapi]
```

### Quick Start

```python
from argus.core.openapi import (
    load_openapi_spec,
    OpenAPIParser,
    OpenAPIClient,
    OpenAPIToolGenerator,
)

# Load OpenAPI spec (JSON, YAML, or URL)
spec = load_openapi_spec("https://api.example.com/openapi.json")

# Parse the specification
parser = OpenAPIParser()
api_spec = parser.parse(spec)

print(f"API: {api_spec.title} v{api_spec.version}")
print(f"Endpoints: {len(api_spec.operations)}")
```

### Dynamic Client Generation

```python
from argus.core.openapi import create_client

# Create a dynamic REST client from any OpenAPI spec
client = create_client(
    spec_path="https://petstore.swagger.io/v2/swagger.json",
    api_key="your-api-key",  # Or bearer_token, basic_auth
)

# Methods are generated automatically from the spec
pets = client.get_pets(limit=10)
pet = client.get_pet_by_id(pet_id=123)
new_pet = client.create_pet(name="Fluffy", status="available")
```

### Tool Code Generation

Generate complete tool implementations for agent use:

```python
from argus.core.openapi import generate_tool_code

# Generate a full BaseTool implementation
code = generate_tool_code(
    spec_path="./api_spec.yaml",
    class_name="PetStoreTool",
)

# Save to file
with open("petstore_tool.py", "w") as f:
    f.write(code)

# The generated tool can be immediately used:
# from petstore_tool import PetStoreTool
# tool = PetStoreTool()
# result = tool(action="get_pets", limit=10)
```

### CLI Usage

```bash
# List available endpoints
argus openapi ./api_spec.yaml --list-endpoints

# Validate a spec
argus openapi https://api.example.com/openapi.json --validate

# Generate tool code
argus openapi ./api_spec.yaml --output my_tool.py --class-name MyAPITool
```

### Authentication

```python
from argus.core.openapi import create_client

# API Key authentication
client = create_client(spec_path="./spec.yaml", api_key="sk-xxx")

# Bearer token authentication
client = create_client(spec_path="./spec.yaml", bearer_token="eyJ...")

# Basic authentication
client = create_client(spec_path="./spec.yaml", basic_auth=("user", "pass"))
```

---

## Context Caching

ARGUS v3.1 includes a comprehensive caching system for optimizing context management, reducing API costs, and improving performance.

### Features

- **Multiple backends**: Memory (LRU), File (persistent), Redis (distributed)
- **Specialized caches**: Conversation, Embedding, LLM Response
- **TTL support**: Automatic expiration
- **Namespaces**: Isolated cache spaces
- **Statistics**: Hit rates, access patterns

### Installation

```bash
pip install argus-debate-ai[context]
```

### Quick Start

```python
from argus.core.context_caching import (
    ContextCache,
    MemoryBackend,
    FileBackend,
    ConversationCache,
    EmbeddingCache,
    LLMResponseCache,
)

# Simple in-memory cache
cache = ContextCache(backend=MemoryBackend())
cache.set("key", {"data": "value"}, ttl=3600)
result = cache.get("key")

# Persistent file cache
cache = ContextCache(
    backend=FileBackend(cache_dir=".argus_cache"),
    namespace="my_app",
)
```

### Conversation Cache

Efficiently manage multi-turn conversation history:

```python
from argus.core.context_caching import ConversationCache

# Create conversation cache
conv_cache = ConversationCache(max_messages=100, max_tokens=8000)

# Add messages
conv_cache.add_message("user", "Hello, how are you?")
conv_cache.add_message("assistant", "I'm doing well, thank you!")

# Get conversation for LLM
messages = conv_cache.get_messages()

# Get recent context with token limit
context = conv_cache.get_recent_context(max_tokens=4000)

# Summarize old messages to save space
conv_cache.summarize_and_truncate(llm=your_llm, keep_recent=10)
```

### Embedding Cache

Cache embeddings to reduce API calls:

```python
from argus.core.context_caching import EmbeddingCache

# Create embedding cache
embed_cache = EmbeddingCache(
    backend=FileBackend(cache_dir=".embeddings_cache"),
    model_name="text-embedding-3-small",
)

# Check cache before calling API
text = "Hello world"
cached = embed_cache.get(text)
if cached is None:
    # Generate embedding
    embedding = your_embedder.embed(text)
    embed_cache.set(text, embedding)
else:
    embedding = cached

# Batch operations
texts = ["doc1", "doc2", "doc3"]
cached, missing = embed_cache.get_batch(texts)
# Only generate embeddings for missing texts
```

### LLM Response Cache

Cache LLM responses for identical inputs:

```python
from argus.core.context_caching import LLMResponseCache

# Create response cache (deterministic key from prompt + params)
response_cache = LLMResponseCache(
    backend=MemoryBackend(max_size=1000),
    default_ttl=86400,  # 24 hours
)

# Cache lookup
prompt = "Explain machine learning"
params = {"model": "gpt-4", "temperature": 0}

cached = response_cache.get(prompt, **params)
if cached is None:
    response = llm.generate(prompt, **params)
    response_cache.set(prompt, response, **params)
else:
    response = cached
```

### Decorator Pattern

```python
from argus.core.context_caching import ContextCache

cache = ContextCache(backend=MemoryBackend())

@cache.cached(ttl=3600)
def expensive_computation(input_data: str) -> dict:
    # This will be cached
    return {"result": process(input_data)}
```

### CLI Usage

```bash
# Show cache statistics
argus cache stats --backend file --path .argus_cache

# Clear cache
argus cache clear --backend memory

# Export cache (for debugging/migration)
argus cache export --path ./cache_backup
```

---

## Context Compression

ARGUS v3.1 includes advanced compression techniques to reduce token usage while preserving meaning.

### Features

- **Multiple compression methods**: Whitespace, Punctuation, Stopword, Sentence, Code, Semantic
- **Compression levels**: Minimal, Moderate, Aggressive, Extreme
- **Token counting**: Accurate token estimation with tiktoken
- **Message compression**: Optimize conversation history
- **Auto-detection**: Automatically select best method for content type

### Installation

```bash
pip install argus-debate-ai[context]
```

### Quick Start

```python
from argus.core.context_compression import (
    compress_text,
    compress_to_tokens,
    CompressionLevel,
)

# Simple compression
result = compress_text(
    "This is a   very    long text   with   lots of   whitespace...",
    level=CompressionLevel.MODERATE,
)
print(result.compressed_text)
print(f"Savings: {result.savings_percentage:.1f}%")

# Compress to target token count
result = compress_to_tokens(long_text, target_tokens=1000)
print(f"Tokens saved: {result.tokens_saved}")
```

### Compression Methods

```python
from argus.core.context_compression import (
    WhitespaceCompressor,
    StopwordCompressor,
    SentenceCompressor,
    CodeCompressor,
    SemanticCompressor,
)

# Whitespace compression (fastest, safest)
compressor = WhitespaceCompressor()
result = compressor.compress("Hello    world")  # "Hello world"

# Stopword removal (moderate compression)
compressor = StopwordCompressor()
result = compressor.compress("This is a very important document")
# "very important document"

# Sentence compression (keeps important sentences)
compressor = SentenceCompressor(ratio=0.5, min_sentences=3)
result = compressor.compress(long_document)

# Code compression (minifies code while preserving syntax)
compressor = CodeCompressor()
result = compressor.compress(python_code)

# Semantic compression (LLM-based, best quality)
compressor = SemanticCompressor(llm=your_llm)
result = compressor.compress(document, target_ratio=0.3)
```

### Message Compression

Compress conversation history for LLM context:

```python
from argus.core.context_compression import MessageCompressor

compressor = MessageCompressor(
    max_tokens=4000,
    preserve_system=True,  # Keep system messages intact
    preserve_recent=5,      # Keep last 5 messages intact
)

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Long user message..."},
    {"role": "assistant", "content": "Long assistant response..."},
    # ... many more messages
]

compressed = compressor.compress(messages)
print(f"Messages: {len(messages)} -> {len(compressed)}")
```

### Context Compressor (Auto)

Automatically detect content type and apply best compression:

```python
from argus.core.context_compression import ContextCompressor

compressor = ContextCompressor()

# Auto-detects content type and applies appropriate method
result = compressor.auto_compress(
    content=mixed_content,
    target_tokens=2000,
)

# Analyze content before compression
analysis = compressor.analyze(content)
print(f"Type: {analysis['content_type']}")
print(f"Current tokens: {analysis['token_count']}")
print(f"Recommended method: {analysis['recommended_method']}")
```

### CLI Usage

```bash
# Compress a file
argus compress input.txt --output compressed.txt --level moderate

# Compress to token target
argus compress input.txt --target-tokens 1000

# Specific compression method
argus compress code.py --method code --output minified.py
```

---

## Debate Visualization

ARGUS v3.1 includes a comprehensive visualization module for debate analysis and presentation.

### Features

- **Argument flow graphs**: NetworkX-based directed graphs
- **Timeline visualization**: Temporal argument progression
- **Agent performance charts**: Multi-metric agent analysis
- **Confidence evolution**: Rolling average tracking
- **Round summaries**: Per-round statistics
- **Interaction heatmaps**: Agent collaboration patterns
- **Interactive dashboards**: Combined multi-panel views
- **Export formats**: HTML, PNG, JSON reports

### Installation

```bash
pip install argus-debate-ai[plotting]
```

### Quick Start

```python
from argus.debate.visualization import (
    DebateSession,
    create_debate_dashboard,
    export_debate_html,
    plot_argument_flow,
)

# Load debate data
with open("debate_results.json") as f:
    data = json.load(f)

session = DebateSession.from_dict(data)

# Create comprehensive dashboard
fig = create_deb