adaptive-intelligence 1.0.3

Self-improving retrieval orchestration framework with RL-based routing, conditional graph activation, and evaluation-driven learning.

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.

• 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

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())

# 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.

# 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.

# 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

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

# 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

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 - Summary

• User Query enters the system as natural language.

• Trigger Interpreter classifies query type, complexity, domain, and extracts entities.

• RL Policy Engine selects the optimal retrieval strategy using Thompson Sampling.

• Retrieval Orchestrator queries the chosen index (Vector, Keyword, Graph, Table, or Hybrid).

• Graph Index activates only when a five-signal gate detects relationship reasoning is needed.

• Adaptive Prompt Engine builds a domain-aware prompt from evolving templates.

• LLM Generation produces the answer using any model (Ollama, OpenAI, Grok, Claude).

• Evaluation Engine scores the answer on faithfulness, relevance, hallucination, and citations.

• Reward Signal feeds the evaluation score back to update the RL policy.

• Response returns the answer with confidence score, sources, and audit trail.

---

System Prompt

Customize the LLM's behavior at three levels:

# Level 1: Set at init (applies to all queries)
engine = AdaptiveAI(
    llm_backend="openai",
    api_key="...",
    system_prompt="You are a financial analyst. Always cite page numbers. Use bullet points for key findings."
)

# Level 2: Override per query
response = engine.ask(
    "What are the key risks?",
    system_prompt="You are a risk specialist. Rate each risk HIGH/MEDIUM/LOW."
)

# Level 3: Update anytime
engine.set_system_prompt(
    "You are a legal compliance reviewer. Flag regulatory violations. Cite clause numbers."
)

# Reset to default
engine.set_system_prompt(None)

Priority: ask() param → init param → default.

---

FAQ

Q: How does ingestion handle mixed content (text + tables) from PDFs?

Tables are extracted with structure preserved (is_table=True) and indexed into the same Vector + Keyword indexes as text. The RL policy learns to use the table_first retrieval route for structured queries. Separation happens at retrieval time via learned routing, not at ingestion time.

Q: How is this different from just using ChatGPT / Claude?

Adaptive Intelligence is not an LLM — it's the retrieval layer that decides what context to feed TO the LLM. It uses ChatGPT, Claude, Grok, or Ollama as backends. The system learns which retrieval strategy works best for each query type on YOUR specific documents. No LLM can do that alone.

Q: Does the RL policy persist across sessions?

Yes. The RL policy state, learning memory, and vector index are saved to the storage_dir (default: .adaptive_intelligence/). The system picks up where it left off.

Q: Can I use this without an LLM (offline)?

Yes. Without an LLM, engine.ask() returns ranked source excerpts directly from the retrieved chunks. The RL policy, graph, and evaluation still work — only the synthesis step falls back to direct excerpts.

---

Also by the Author

• llmevalkit — LLM evaluation, hallucination detection, compliance, and 61 metrics
• Responsible AI Series — HIPAA, GDPR, NIST AI RMF, CoSAI, EU AI Act

Citation

@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/