ARKIS

Adaptive Retrieval & Knowledge Intelligence System

A conservative, research-grade agentic RAG system that prioritizes evidence-grounded answers over hallucination. ARKIS answers only when claims can be explicitly supported by retrieved evidence.

---

Why ARKIS?

Most RAG systems fail silently by hallucinating when retrieval is weak. ARKIS takes a fundamentally different approach:

Feature	Typical RAG	ARKIS
Always answers	Yes	No - refuses when evidence is missing
Hallucination risk	High	Near-zero
Evidence extraction	Implicit	Explicit with relevance scoring
Contradiction handling	None	Automatic detection & flagging
Partial answers	No	Yes - honest when evidence is sparse
Citations	Optional	Mandatory
Domain validation	No	Yes - rejects out-of-scope queries

---

Key Features

Core Capabilities

• Evidence-Grounded Answers - Every claim must map to a specific document chunk
• Domain Gating - Rejects queries outside the knowledge base scope
• Partial-Answer Policy - Provides honest, limited answers when evidence is sparse
• Mandatory Citations - Every response includes source references

Pillar 2: Stronger Evidence Reasoning (v2.0)

• Evidence Scoring - Ranks evidence by relevance to the query
• Statement Clustering - Groups similar evidence, removes redundancy
• Contradiction Detection - Identifies conflicting information across sources
• Confidence Penalties - Reduces confidence when sources conflict

Professional UI

• Streamlit Dashboard - Modern, dark-themed interface
• Real-time Streaming - Watch answers generate token-by-token
• Document Management - Upload and manage knowledge base documents
• Knowledge Gap Analytics - Track and analyze unanswered queries

---

Quick Start

Prerequisites

• Python 3.11+
• Docker & Docker Compose
• Ollama with llama3.1:8b model

1. Clone and Install

git clone https://github.com/yourusername/arkis-rag.git
cd arkis-rag

# Install dependencies
pip install -e .
# or with poetry
poetry install

2. Start Infrastructure

docker compose up -d

This starts:

• Qdrant (vector database) on port 6333
• PostgreSQL on port 5432
• Redis on port 6379

3. Start Ollama

ollama run llama3.1:8b

4. Ingest Documents

python scripts/ingest_docs.py data/documents

5. Run the API

uvicorn api.main:app --reload

6. Launch the UI

streamlit run ui/app.py

Open http://localhost:8501 in your browser.

---

API Reference

Query Endpoint

POST /query
Content-Type: application/json

{
  "query": "What are adversarial patches in machine learning?"
}

Response:

{
  "answer": "Adversarial patches are learned patterns...",
  "confidence": 0.85,
  "partial_answer": false,
  "citations": [
    {"source": "adversarial_ml.pdf", "chunk_id": "abc123"}
  ],
  "evidence_stats": {
    "total_extracted": 8,
    "after_deduplication": 5,
    "clusters_formed": 3
  },
  "has_contradictions": false,
  "contradiction_penalty": 0.0
}

Streaming Endpoint

POST /stream
Content-Type: application/json

{
  "query": "What are adversarial patches?"
}

Returns Server-Sent Events (SSE) with real-time progress updates.

Document Upload

POST /documents/upload
Content-Type: multipart/form-data

file: <your_document.pdf>

Other Endpoints

Endpoint	Method	Description
/health	GET	Health check
/gaps	GET	List knowledge gaps
/gaps/stats	GET	Gap statistics
/gaps/dashboard	GET	Full dashboard data
/documents/list	GET	List uploaded documents

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         ARKIS v2.0                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐    │
│  │  Domain  │ → │ Retrieve │ → │ Extract  │ → │  Score   │    │
│  │   Gate   │   │          │   │ Evidence │   │ Cluster  │    │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘    │
│        │                                            │          │
│        │ (mismatch)                                 ↓          │
│        │                                     ┌──────────┐      │
│        │                                     │ Detect   │      │
│        │                                     │ Conflicts│      │
│        │                                     └──────────┘      │
│        │                                            │          │
│        ↓                                            ↓          │
│  ┌──────────┐                               ┌──────────┐      │
│  │ Curator  │ ← ─ ─ (low confidence) ─ ─ ─  │Synthesize│      │
│  │  Agent   │                               │          │      │
│  └──────────┘                               └──────────┘      │
│        │                                            │          │
│        │                                            ↓          │
│        │                                     ┌──────────┐      │
│        └─────────────────────────────────→   │ Validate │      │
│                                              └──────────┘      │
│                                                    │           │
│                                                    ↓           │
│                                              ┌──────────┐      │
│                                              │ Response │      │
│                                              └──────────┘      │
└─────────────────────────────────────────────────────────────────┘

Agent Pipeline

1. Domain Gate - Classifies query domain, rejects out-of-scope queries
2. Retrieval Agent - Dense retrieval + cross-encoder reranking
3. Evidence Extraction - Extracts grounded statements from chunks
4. Evidence Scoring - Scores relevance, clusters similar statements
5. Contradiction Detection - Identifies conflicts between sources
6. Synthesis Agent - Generates evidence-bounded answer
7. Validation Agent - Checks grounding, applies confidence penalties
8. Curator Agent - Logs knowledge gaps, returns honest fallback

---

Project Structure

arkis-rag/
├── agents/                    # LangGraph agents
│   ├── orchestrator.py        # Graph definition
│   ├── state.py               # State schema
│   ├── domain_classifier.py   # Domain gating
│   ├── retrieval_agent.py     # Retrieval logic
│   ├── evidence_agent.py      # Evidence extraction
│   ├── evidence_scoring_agent.py    # Scoring & clustering
│   ├── contradiction_agent.py       # Conflict detection
│   ├── synthesis_agent.py     # Answer generation
│   ├── validation_agent.py    # Grounding validation
│   └── curator_agent.py       # Knowledge gap handling
├── api/                       # FastAPI application
│   ├── main.py
│   └── routes/
│       ├── query.py           # Main query endpoint
│       ├── stream.py          # SSE streaming
│       ├── documents.py       # Document management
│       ├── gaps.py            # Knowledge gap API
│       └── health.py
├── core/                      # Core components
│   ├── documents.py           # Document loading & chunking
│   ├── embeddings.py          # Embedding service
│   ├── vectorstore.py         # Qdrant interface
│   ├── retrieval.py           # Adaptive retrieval
│   ├── reranker.py            # Cross-encoder reranker
│   └── llm.py                 # LLM client
├── config/
│   └── settings.py            # Configuration
├── ui/
│   └── app.py                 # Streamlit UI
├── data/
│   ├── documents/             # Knowledge base documents
│   ├── uploads/               # User uploads
│   └── logs/                  # Knowledge gap logs
├── tests/                     # Test suite
├── docs/                      # Documentation
├── docker-compose.yml
├── pyproject.toml
└── README.md

---

Configuration

Configuration is managed in config/settings.py with environment variable overrides.

Key Settings

Setting	Default	Description
CHUNK_SIZE	512	Document chunk size
CHUNK_OVERLAP	50	Overlap between chunks
TOP_K_RETRIEVAL	5	Final chunks returned
TOP_K_RERANK	20	Chunks sent to reranker
VALIDATION_THRESHOLD	0.7	Minimum confidence
GAP_THRESHOLD	0.5	Knowledge gap trigger
EVIDENCE_CLUSTER_THRESHOLD	0.85	Clustering similarity
EVIDENCE_MIN_RELEVANCE	0.3	Minimum relevance score

Environment Variables

Create a .env file:

QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=arkis_chunks
OLLAMA_URL=http://localhost:11434
KB_DOMAINS=machine_learning,artificial_intelligence,deep_learning

---

Development

Running Tests

# All tests
pytest

# Specific test file
pytest tests/test_evidence_scoring.py -v

# With coverage
pytest --cov=agents --cov=core

Code Quality

# Linting
ruff check .

# Formatting
black .

---

Supported Document Formats

Format	Extension	Description
PDF	.pdf	Research papers, reports
Text	.txt	Plain text files
Markdown	.md	Documentation
Word	.docx	Microsoft Word documents

---

Tech Stack

Component	Technology
Orchestration	LangGraph
Vector Database	Qdrant
Embeddings	BAAI/bge-large-en-v1.5
Reranker	BAAI/bge-reranker-large
LLM	Ollama (llama3.1:8b)
API	FastAPI
UI	Streamlit
Database	PostgreSQL
Cache	Redis

---

Roadmap

• v1.0 - Core agentic RAG with evidence grounding
• v2.0 - Evidence scoring, clustering, contradiction detection
• v2.1 - Hybrid retrieval (dense + BM25)
• v2.2 - Multi-document reasoning
• v3.0 - Learning from feedback
• v3.1 - Temporal awareness

---

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• LangGraph for agent orchestration
• Qdrant for vector search
• Sentence Transformers for embeddings
• Ollama for local LLM inference

---

ARKIS - Because research demands truth, not hallucination.