Warning
Experimental Software / Reference and Integration Foundation This repository is an experimental codebase and integration foundation for self-hosted or locally operated deployments. It does not provide a complete production-ready security configuration, hardened deployment profile, or any assurance that it is suitable for direct use in internet-facing, multi-user, regulated, or otherwise high-risk environments.
Configurations, defaults, example values, example scripts, and helper paths included in this repository may be useful for development, testing, or integration work, but must not be assumed to be secure, complete, or appropriate for production use without independent review and adaptation.
Secure configuration, hardening, deployment architecture, access control, secret handling, logging, monitoring, compliance, and day-to-day operation remain the sole responsibility of the operator. The current test suite covers substantial internal logic, interface behavior, and regression scenarios, but it is not evidence of production readiness or fully validated live integrations. Perform your own technical and security review before using this project in integration, staging, test, or production environments.
License: Apache 2.0 Python: 3.12+
Self-hostable Python library and HTTP server for an iterative AI research agent with parallel web search, claim verification, and source tiering.
Inqtrix runs a bounded multi-round research loop: it decomposes a question, searches the web in parallel, extracts and verifies claims against multiple sources, and synthesises a cited answer once evidence quality thresholds are met.
- Iterative research loop with configurable confidence threshold and max rounds.
- Parallel web search with LLM-based summarisation and structured claim extraction (non-fatal per-source fallback).
- Claim verification — claims are consolidated, deduplicated, and classified as
verified,contested, orunverified. - Source tiering — URLs are classified into five quality tiers (primary, mainstream, stakeholder, unknown, low).
- Aspect coverage tracking ensures all facets of a question get researched before the agent commits to high confidence.
- 9 stop heuristics — confidence, utility plateau, stagnation, falsification mode, and more.
- Report profiles — switch between compact default answers and longer deep-review style reports.
- Pluggable architecture — swap LLM providers, search engines, and strategies independently (Baukasten).
- Pydantic configuration — type-safe, serialisable, IDE-friendly.
- OpenAI-compatible HTTP API — drop-in replacement for
/v1/chat/completions. - Native run API for UIs —
/v1/runsadds queueing, structured SSE progress events, cancellation, and short-lived result retrieval for React-style frontends.
flowchart LR
U["User / Application"] --> A["ResearchAgent"]
A --> G["LangGraph<br/>5 nodes"]
G --> L["LLM provider<br/>LiteLLM / Anthropic / Azure / Bedrock"]
G --> S["Search provider<br/>Perplexity / Brave / Azure Web Search"]
G --> R["ResearchResult<br/>(answer, metrics, claims, sources)"]
R --> U
Start with the documentation hub for task-oriented navigation. Full technical reference: docs/architecture/overview.md and docs/architecture/graph-topology.md.
Option A — with uv (recommended):
git clone https://github.com/BZandi/inqtrix.git
cd inqtrix
uv sync --extra dev
source .venv/bin/activate
cp .env.example .env
# edit .env with your provider credentialsOption B — with pip (standard library venv):
git clone https://github.com/BZandi/inqtrix.git
cd inqtrix
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# edit .env with your provider credentialsThe project uses a
src/layout, so an editable install (-e) is required forimport inqtrixto work. See Installation for details.
# main.py
from inqtrix import ResearchAgent
agent = ResearchAgent()
result = agent.research("Was ist der aktuelle Stand der GKV-Reform?")
print(result.answer)
print(f"Confidence: {result.metrics.confidence}/10 "
f"Sources: {result.metrics.total_citations} "
f"Rounds: {result.metrics.rounds}")# uv
uv run python main.py
# pip (with .venv activated)
python main.pyOffline regression check (no API calls):
# uv
uv run pytest tests/ -v
# pip (with .venv activated)
pytest tests/ -vMore entry paths (explicit providers, YAML routing, streaming, HTTP): Library mode, Web server mode.
Ready-made examples (no main.py required): examples/README.md.
HTTP server (OpenAI-compatible API) — after .env is configured, start the default FastAPI app (port 5100 by default, override with INQTRIX_SERVER_PORT):
uv run python -m inqtrixSee Web server mode for TLS, API keys, and CORS.
In addition to the bundled Streamlit frontend below, Inqtrix now contains the foundation for a dedicated React + Vite + shadcn web interface in apps/research-desk. The goal is a more native-feeling research desk for iterative AI research runs, not just another chat screen.
Each submitted question becomes its own research job card. Active jobs continue to stream their current iteration steps directly inside the card while the user can start additional research tasks from the composer. Completed jobs can be opened on demand in a right-side Markdown report viewer, designed to present the final answer as a clean report-style document.
The planned UI focuses on:
- research job cards instead of a single linear chat history,
- live progress streams for planning, search, evaluation, and answer synthesis,
- parallel task handling so new research can be started while earlier runs continue,
- compact per-run metadata such as confidence, rounds, sources, and queries,
- optional Markdown report viewing for completed research results,
- shadcn-based enterprise design with a light, professional interface.
This is currently a foundation slice. Install with pnpm install --frozen-lockfile, run locally with pnpm run ui:dev, and build with pnpm run ui:build; the generated apps/research-desk/dist/ directory is intentionally not committed. See React UI for setup, security, build, and deployment notes. The Streamlit UI remains the bundled frontend for local operation, demos, and integration testing until the React UI is integrated as a first-class frontend.
The bundled webapp.py is a production-shaped Streamlit
frontend for the HTTP server. It discovers the available stacks via
GET /v1/stacks, streams answers plus progress events over SSE, and
exposes the whitelisted per-request agent_overrides (report_profile,
max_rounds/min_rounds via the effort selector, confidence_stop,
max_total_seconds, first_round_queries, enable_de_policy_bias, and
skip_search when web search is disabled) through the composer menus
underneath the chat input. See Streamlit UI
for the full mapping.
# Terminal 1 — multi-stack HTTP server (single-stack examples work too)
uv run python examples/webserver_stacks/multi_stack.py
# Terminal 2 — Streamlit UI
uv sync --extra ui
INQTRIX_WEBAPP_BASE_URL=http://localhost:5100 \
uv run streamlit run webapp.pyWhen the server has the Bearer gate enabled
(INQTRIX_SERVER_API_KEY=...), set INQTRIX_WEBAPP_API_KEY to the same
token. No other configuration is read by the UI — it is a pure HTTP
consumer and deliberately does not import the inqtrix package. See
Authentication and TLS
for an end-to-end walkthrough (server-side env vars, curl / httpx /
requests client snippets).
Note on third-party terms of service: Inqtrix is provider-neutral. You bring your own API keys and choose which search and LLM providers to wire in. Whether each provider's terms of service permit your specific Inqtrix use case is your responsibility to verify. In particular, Brave Search and Microsoft Bing Grounding impose specific restrictions on AI- and agent-style use cases; please review their terms before any deployment.
The provider-stack examples share the same provider construction byte-for-byte between provider_stacks/ and webserver_stacks/ — library vs HTTP is the only difference. Custom-provider examples show the same constructor-first pattern for ad-hoc combinations.
The full navigation lives in the documentation hub. Common entry points:
| Need | Start here |
|---|---|
| First setup and first live run | Installation, First research run |
| Runnable examples | Examples index |
| Library integration | Library mode, Agent config |
| HTTP server and Streamlit UI | Web server mode, Streamlit UI |
| Provider selection and custom adapters | Providers overview, Writing a custom provider |
| Logs, debugging, and test workflows | Debugging runs, Troubleshooting, Running tests |
- New to the agent? Overview → First research run.
- Integrating into your app? Library mode and Providers overview.
- Deploying as a service? Web server mode, Enterprise Azure, Security hardening.
- Customising behaviour? Strategies, Stop criteria, Writing a custom provider.
- Contributing? Contributing and Coding standards.
Copyright (c) 2026 Babak Zandi.
This project is licensed under the Apache License 2.0. See the LICENSE file for the full license text, warranty disclaimer, and limitation of liability.
Inqtrix is built on the following open-source libraries:
| Library | License | Purpose |
|---|---|---|
| FastAPI | MIT | HTTP server and API endpoints |
| Uvicorn | BSD-3-Clause | ASGI server |
| OpenAI Python SDK | Apache-2.0 | LLM and search provider communication |
| LangGraph | MIT | State machine orchestration |
| Pydantic / Pydantic Settings | MIT | Data validation and configuration |
| cachetools | MIT | TTL-based search result caching |
| PyYAML | MIT | YAML configuration loading |
Dev dependencies:
| Library | License | Purpose |
|---|---|---|
| pytest | MIT | Test framework |
| pytest-asyncio | Apache-2.0 | Async test support |
| vcrpy / pytest-recording | MIT / MIT | HTTP replay testing |
| Requests | Apache-2.0 | HTTP client for integration tests |
When configured to use external model, search, or API providers, this project may transmit prompts, context, search queries, and related request data to those third-party services.
Use of third-party services is governed by their respective terms, privacy policies, and data-processing practices. Users and operators are solely responsible for ensuring that their use of this project and any connected services complies with applicable law, contractual obligations, confidentiality requirements, and internal policies. Do not assume that any provider integration, default configuration, or example workflow included in this repository satisfies your legal, security, or data-protection obligations.
Outputs generated by this project or by connected third-party providers are provided for informational purposes only and do not constitute legal, medical, financial, or other professional advice. Independent verification remains the responsibility of the user.
This project was developed with assistance from AI tools:
- Claude Code (Anthropic)
- GitHub Copilot (GitHub / Microsoft)
- ChatGPT (OpenAI)
This disclosure is provided for transparency only. Use of this project remains subject to the terms of the Apache License 2.0, including the "as is" disclaimer and limitation of liability.