Metadata-Version: 2.4
Name: adaptive-intelligence
Version: 1.0.1
Summary: Self-improving retrieval orchestration framework with RL-based routing, conditional graph activation, and evaluation-driven learning.
Author-email: Venkatkumar Rajan <venkatkumarr.vk99@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://pypi.org/project/adaptive-intelligence/
Project-URL: Documentation, https://github.com/VK-Ant/adaptive-intelligence#readme
Project-URL: Repository, https://github.com/VK-Ant/adaptive-intelligence
Project-URL: Issues, https://github.com/VK-Ant/adaptive-intelligence/issues
Project-URL: PyPI, https://pypi.org/project/adaptive-intelligence/
Project-URL: Portfolio, https://vk-ant.github.io/Venkatkumar/
Keywords: rag,retrieval,reinforcement-learning,knowledge-graph,document-intelligence,adaptive,self-improving,llm,ai,nlp,evaluation,self-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: chromadb>=0.4.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: groq
Requires-Dist: openai>=1.0.0; extra == "groq"
Provides-Extra: pdf
Requires-Dist: PyMuPDF>=1.23.0; extra == "pdf"
Provides-Extra: docx
Requires-Dist: python-docx>=1.0.0; extra == "docx"
Provides-Extra: xlsx
Requires-Dist: openpyxl>=3.1.0; extra == "xlsx"
Provides-Extra: pptx
Requires-Dist: python-pptx>=0.6.21; extra == "pptx"
Provides-Extra: ocr
Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
Requires-Dist: Pillow>=10.0; extra == "ocr"
Provides-Extra: huggingface
Requires-Dist: transformers>=4.35.0; extra == "huggingface"
Requires-Dist: torch>=2.0.0; extra == "huggingface"
Provides-Extra: all
Requires-Dist: PyMuPDF>=1.23.0; extra == "all"
Requires-Dist: python-docx>=1.0.0; extra == "all"
Requires-Dist: openpyxl>=3.1.0; extra == "all"
Requires-Dist: python-pptx>=0.6.21; extra == "all"
Requires-Dist: pytesseract>=0.3.10; extra == "all"
Requires-Dist: Pillow>=10.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Dynamic: license-file

# adaptive-intelligence

Self-improving retrieval orchestration framework for document intelligence. Drop documents, ask questions, the system learns how to retrieve better over time.

RL-based retrieval routing, conditional graph activation, evaluation-driven learning, and zero-configuration architecture. Works with any LLM.

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/VK-Ant/adaptive-intelligence/blob/main/notebooks/traditional_rag_vs_adaptive_intelligence.ipynb)

- PyPI: https://pypi.org/project/adaptive-intelligence
- GitHub: https://github.com/VK-Ant/adaptive-intelligence
- Portfolio: https://vk-ant.github.io/Venkatkumar

## Install

```
pip install adaptive-intelligence
pip install adaptive-intelligence[pdf]          # adds PDF support
pip install adaptive-intelligence[all]          # all document formats
pip install adaptive-intelligence[huggingface]  # local HuggingFace models
```

---

## Quick Start

```python
from adaptive_intelligence import AdaptiveAI

# Zero config — defaults to Ollama (free, local, private)
engine = AdaptiveAI()
engine.ingest("./documents")
response = engine.ask("What are the key operational risks?")

print(response.answer)
print(f"Confidence: {response.confidence:.0%}")
print(response.evaluation.display())
```

```python
# With Grok API
engine = AdaptiveAI(
    llm_backend="openai",
    llm_model="grok-3-mini",
    api_key="xai-...",
    base_url="https://api.x.ai/v1",
    domain="financial",
)

# With OpenAI
engine = AdaptiveAI(
    llm_backend="openai",
    llm_model="gpt-4o",
    api_key="sk-...",
)
```

---

## What Makes This Different

| | Traditional RAG | Adaptive Intelligence |
|---|---|---|
| Retrieval | Static vector similarity | RL-learned routing (6 strategies) |
| Graph | None | Conditional activation (5-signal gate) |
| Prompts | Fixed template | Domain-adaptive, evolving |
| Learning | Same performance forever | Improves with each query |
| Evaluation | Manual | Automatic 6-metric + RL reward |

---

## Three Core Innovations

### 1. RL Policy Engine

Contextual bandits with Thompson Sampling learn which retrieval strategy works best for each query type. First 15 queries use heuristic defaults, then RL takes over. No hardcoded rules.

```python
# The RL policy decides per query:
# - Retrieval route: vector, keyword, hybrid, table-first, graph-hybrid
# - Retrieval depth: 3, 5, 8, 10, 15 chunks
# - Graph activation: on/off
# - Prompt template: extraction, analysis, summary, comparison
# - Verification level: none, citation, full
```

### 2. Conditional Graph Activation

Knowledge graph built automatically during ingestion. Activated only when the query needs relational reasoning — not wasted on simple factual lookups.

Five signals gate activation: relationship words, query analysis, entity density, complexity, historical success rate.

### 3. Self-Adaptive Retrieval

Every response evaluated on 6 metrics. Composite score becomes RL reward. System measurably improves over queries.

```python
# Evaluation metrics (all automatic, no ground truth needed):
# - Faithfulness: grounded in source documents?
# - Relevance: addresses the query?
# - Citation accuracy: sources cited?
# - Hallucination risk: fabricated content?
# - Retrieval precision: relevant chunks retrieved?
# - Retrieval recall: query terms covered?
```

---

## Supported Formats

| S.No. | Format | Extension | Required Package |
|-------|--------|-----------|-----------------|
| 1 | Text / Markdown | .txt, .md | — |
| 2 | CSV | .csv | — |
| 3 | JSON | .json | — |
| 4 | HTML | .html | — |
| 5 | XML | .xml | — |
| 6 | PDF | .pdf | `PyMuPDF` or `pdfplumber` |
| 7 | Word | .docx | `python-docx` |
| 8 | Excel | .xlsx | `openpyxl` |
| 9 | PowerPoint | .pptx | `python-pptx` |
| 10 | Images (OCR) | .png, .jpg | `pytesseract`, `Pillow` |

## Supported LLM Providers

| S.No. | Provider | Backend | Local? | Free? |
|-------|----------|---------|--------|-------|
| 1 | Ollama | `ollama` | Yes | Yes |
| 2 | OpenAI | `openai` | No | No |
| 3 | Grok (xAI) | `openai` | No | No |
| 4 | Azure OpenAI | `azure_openai` | No | No |
| 5 | Groq | `groq` | No | Free tier |
| 6 | Together AI | `together` | No | Free tier |
| 7 | HuggingFace | `huggingface` | Yes | Yes |
| 8 | Any OpenAI-compatible | `custom` | Varies | Varies |

---

## Code Examples

### Inspect the Full Pipeline

```python
response = engine.ask("Compare Q2 and Q3 revenue")

# What did the system understand?
print(response.query_analysis)

# What strategy did the RL policy choose?
pd = response.policy_decision
print(f"Route: {pd.retrieval_route}")
print(f"Graph: {pd.graph_activation}")
print(f"Explored: {pd.was_exploration}")

# Evaluation scores
print(response.evaluation.display())

# Citations
for c in response.citations:
    print(f"  {c.source_document} ({c.confidence:.0%})")
```

### Dashboard and Monitoring

```python
# System dashboard
print(engine.dashboard())

# RL policy stats
stats = engine.rl.get_stats()
print(f"Warmup: {stats['is_warmup']}")
print(f"Arms learned: {stats['total_arms']}")
print(f"Exploration: {stats['exploration_rate']:.1%}")

# Learning curve data
curve = engine.learning_curve()

# Learning memory
print(engine.memory.get_learning_summary())

# Audit trail
print(engine.audit.display_query_trail(response.query_id))
engine.audit.export("audit.json")
```

### Advanced Configuration

```python
from adaptive_intelligence.core.config import (
    AdaptiveConfig, RLConfig, GraphConfig, EvaluationConfig,
    LLMBackend, Domain, SecurityLevel,
)

config = AdaptiveConfig(
    llm_backend=LLMBackend.OLLAMA,
    llm_model="llama3.2",
    domain=Domain.FINANCIAL,
    security_level=SecurityLevel.HIGH,

    rl=RLConfig(
        warmup_queries=20,
        exploration_rate=0.15,
        algorithm="thompson_sampling",
    ),

    graph=GraphConfig(
        enabled=True,
        conditional_activation=True,
        max_hops=3,
    ),

    evaluation=EvaluationConfig(
        faithfulness_weight=0.35,
        enable_llm_judge=True,
    ),
)

engine = AdaptiveAI(config=config)
```

---

## Architecture

![systemarchitecure](docs/images/Screenshot%202026-05-16%20075927.png)

---

## Also by the Author

- **[llmevalkit](https://pypi.org/project/llmevalkit/)** — LLM evaluation, hallucination detection, compliance, and 61 metrics
- **[Responsible AI Series](https://medium.com/@VK_Venkatkumar)** — HIPAA, GDPR, NIST AI RMF, CoSAI, EU AI Act

## Citation

```bibtex
@software{venkatkumar2026adaptive,
  title={Adaptive Intelligence: Self-Improving Retrieval Orchestration via Evaluation-Driven Policy Learning},
  author={Venkatkumar, Rajan},
  year={2026},
  url={https://github.com/VK-Ant/adaptive-intelligence}
}
```

## License

Apache License 2.0

## Author

Venkatkumar Rajan

- LinkedIn: https://linkedin.com/in/venkatkumarvk
- GitHub: https://github.com/VK-Ant
- Portfolio: https://vk-ant.github.io/Venkatkumar/
- PyPI: https://pypi.org/project/adaptive-intelligence/
