Metadata-Version: 2.4
Name: swiss-truth-llamaindex
Version: 0.1.0
Summary: LlamaIndex tools & retriever for Swiss Truth — certified knowledge base for AI agents
Project-URL: Homepage, https://swisstruth.org
Project-URL: Documentation, https://swisstruth.org/docs/llamaindex
Project-URL: Repository, https://github.com/swiss-truth/swiss-truth-mcp
Project-URL: Bug Tracker, https://github.com/swiss-truth/swiss-truth-mcp/issues
Project-URL: PyPI, https://pypi.org/project/swiss-truth-llamaindex
Author-email: Swiss Truth <hello@swisstruth.org>
License: MIT
Keywords: agents,ai,compliance,eu-ai-act,fact-checking,grounding,hallucination,hallucination-prevention,knowledge-base,llama-hub,llama-index,llamahub,llamaindex,mcp,rag,retriever,swiss-truth,tool-spec,verified-facts
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: llama-index-core>=0.11
Requires-Dist: pydantic>=2
Description-Content-Type: text/markdown

# swiss-truth-llamaindex

> **LlamaIndex ToolSpec & Retriever for Swiss Truth — certified knowledge base for AI agents.**

[![PyPI](https://img.shields.io/pypi/v/swiss-truth-llamaindex)](https://pypi.org/project/swiss-truth-llamaindex)
[![Python](https://img.shields.io/pypi/pyversions/swiss-truth-llamaindex)](https://pypi.org/project/swiss-truth-llamaindex)
[![LlamaIndex](https://img.shields.io/badge/LlamaIndex-ToolSpec-blueviolet)](https://llamahub.ai)
[![LlamaHub](https://img.shields.io/badge/LlamaHub-listed-blueviolet)](https://llamahub.ai)
[![EU AI Act](https://img.shields.io/badge/EU_AI_Act-compliant-blue)](https://swisstruth.org/trust)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Stop your LlamaIndex agents from hallucinating. Ground every response in **3,000+ certified facts** across **38 domains** in **10 languages** — verified by Swiss Truth.

---

## Installation

```bash
pip install swiss-truth-llamaindex
```

---

## Quick Start

### Option 1 — ToolSpec (LlamaHub-compatible, recommended)

```python
from swiss_truth_llamaindex import SwissTruthToolSpec
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

# Create the ToolSpec and convert to LlamaIndex tools
spec = SwissTruthToolSpec()
tools = spec.to_tool_list()

# Build a ReAct agent with Swiss Truth grounding
agent = ReActAgent.from_tools(
    tools,
    llm=OpenAI(model="gpt-4o"),
    verbose=True,
)

response = agent.chat("Is health insurance mandatory in Switzerland?")
print(response)
```

### Option 2 — Individual FunctionTools

```python
from swiss_truth_llamaindex import get_all_tools
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

tools = get_all_tools()
agent = ReActAgent.from_tools(tools, llm=OpenAI(model="gpt-4o"), verbose=True)
response = agent.chat("What is the EU AI Act risk classification?")
print(response)
```

### Option 3 — RAG Retriever

```python
from swiss_truth_llamaindex import SwissTruthRetriever
from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.llms.openai import OpenAI

# Domain-scoped retriever
retriever = SwissTruthRetriever(domain="swiss-law", limit=8)

# Use directly
nodes = retriever.retrieve("Is health insurance mandatory in Switzerland?")
for node in nodes:
    print(f"[{node.score:.2f}] {node.node.text}")

# Or plug into a query engine
engine = RetrieverQueryEngine.from_args(
    retriever,
    llm=OpenAI(model="gpt-4o"),
)
response = engine.query("What are the Swiss health insurance rules?")
print(response)
```

---

## Available Tools

All 9 tools are available via `SwissTruthToolSpec` and as individual `FunctionTool` instances:

| Tool | Description |
|------|-------------|
| `search` | Search the certified knowledge base for verified facts |
| `verify` | Verify a single factual claim (VERIFIED / UNVERIFIED / CONTRADICTED) |
| `submit` | Submit a new claim for expert review |
| `list_domains` | List all 38 available knowledge domains |
| `claim_status` | Get the verification status of a claim by UUID |
| `batch_verify` | Verify multiple claims in a single API call |
| `verify_response` | Fact-check an entire LLM response, get hallucination risk score |
| `find_contradictions` | Detect internal contradictions in a block of text |
| `get_compliance` | Generate an EU AI Act compliance report |

---

## API Key

No API key is required for public endpoints. For higher rate limits or private domains, pass your key:

```python
spec = SwissTruthToolSpec(api_key="your-key")
retriever = SwissTruthRetriever(api_key="your-key")
```

---

## Advanced Usage

### Custom client

```python
from swiss_truth_llamaindex import SwissTruthClient, get_all_tools

client = SwissTruthClient(api_key="your-key", timeout=60.0)
tools = get_all_tools(client=client)
```

### Hallucination guard for LLM responses

```python
from swiss_truth_llamaindex import SwissTruthToolSpec

spec = SwissTruthToolSpec()

# After your LLM generates a response, fact-check it:
result = spec.verify_response(
    response_text="Switzerland has 9 million inhabitants and joined the EU in 2002.",
    domain="swiss-facts",
)
print(result)
# → {"hallucination_risk": "HIGH", "claims": [...], "contradicted": [...]}
```

### EU AI Act compliance report

```python
from swiss_truth_llamaindex import SwissTruthToolSpec

spec = SwissTruthToolSpec()
report = spec.get_compliance(domain="ai-ml")
print(report)
```

---

## LlamaHub

This package is listed on [LlamaHub](https://llamahub.ai) as a Tool Spec integration.
You can also load it via the LlamaHub loader:

```python
from llama_index.core import download_loader

SwissTruthToolSpec = download_loader("SwissTruthToolSpec")
spec = SwissTruthToolSpec()
tools = spec.to_tool_list()
```

---

## Links

- 🌐 [Swiss Truth](https://swisstruth.org)
- 📖 [Documentation](https://swisstruth.org/docs/llamaindex)
- 🐍 [PyPI](https://pypi.org/project/swiss-truth-llamaindex)
- 🦙 [LlamaHub](https://llamahub.ai)
- 🔗 [MCP Endpoint](https://swisstruth.org/mcp)
- 🐛 [Issues](https://github.com/swiss-truth/swiss-truth-mcp/issues)

---

## Related Packages

| Framework | Package |
|-----------|---------|
| LangChain | [`swiss-truth-langchain`](https://pypi.org/project/swiss-truth-langchain) |
| CrewAI | [`swiss-truth-crewai`](https://pypi.org/project/swiss-truth-crewai) |
| AutoGen | [`swiss-truth-autogen`](https://pypi.org/project/swiss-truth-autogen) |
| LlamaIndex | [`swiss-truth-llamaindex`](https://pypi.org/project/swiss-truth-llamaindex) ← you are here |

---

## License

MIT © [Swiss Truth](https://swisstruth.org)
