Skip to main content

Maktaba

CI PyPI version Version Python 3.10+ License: MIT

The library for building libraries - By NuhaTech

From the Arabic word for library, Maktaba is a modern RAG infrastructure for building intelligent knowledge systems in any language.

Features

  • 🔌 Provider-agnostic: Works with OpenAI, Cohere, Azure, and more
  • 🚀 Production-ready: Built for scale with async-first design
  • 🧩 Modular: Use only what you need
  • 🌍 Multilingual: Optimized for Arabic and international languages
  • 📊 Type-safe: Full type hints and Pydantic validation
  • 🧪 Well-tested: Comprehensive test coverage
  • 🔍 Deep research: Built-in iterative planning for long-form reports
  • 🧭 Agentic Search v2: Evidence-gap planning, global fusion, graph expansion, provenance, and explicit abstention
  • 📚 Verified collections: Collect an exact number of source-grounded spans with deterministic verification and partial results

Installation

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add maktaba to your project
uv add maktaba

# With OpenAI + Qdrant
uv add "maktaba[openai,qdrant]"

# With all providers
uv add "maktaba[all]"

Using pip

# Basic installation
pip install maktaba

# With OpenAI + Qdrant
pip install "maktaba[openai,qdrant]"

# With all providers
pip install "maktaba[all]"

Quick Start

from maktaba.pipeline import QueryPipeline
from maktaba.embedding import OpenAIEmbedder
from maktaba.storage import QdrantStore
from maktaba.reranking import CohereReranker

# Create pipeline
pipeline = QueryPipeline(
    embedder=OpenAIEmbedder(api_key="..."),
    vector_store=QdrantStore(url="http://localhost:6333", collection_name="docs"),
    reranker=CohereReranker(api_key="...")
)

# Search with automatic reranking and citation formatting
result = await pipeline.search(
    query="What is Tawhid?",
    top_k=10,
    rerank=True
)

# Use in your LLM prompt
print(result["formatted_context"])  # [1]: content... [2]: content...
print(result["citations"])          # [{id: 1, source: "...", score: 0.95}, ...]

Agentic Search v2

from maktaba.pipeline import AgenticQueryPipeline, AgenticSearchConfig

pipeline = AgenticQueryPipeline(
    embedder=embedder,
    store=store,
    keyword_store=keyword_store,
    reranker=reranker,
    llm=llm,
)

result = await pipeline.agentic_search(
    [("user", "Compare the available evidence and identify disagreements")],
    includeRelationships=True,
    config=AgenticSearchConfig(
        max_iterations=4,
        max_total_queries=20,
        token_budget=8_000,
        evidence_limit=15,
    ),
)

if not result["answerable"]:
    print("Insufficient evidence:", result["stop_reason"])
else:
    print(result["formatted_context"])

Agentic v2 preserves the original method and return keys. It adds structured assessment, evidence provenance, iteration traces, bounded relationship expansion, and a fail-closed answerable signal. See AgenticV2.md for the complete contract and migration notes.

Verified evidence collection

from maktaba.pipeline import AgenticCollectionPipeline, CollectionGoal

collector = AgenticCollectionPipeline(pipeline)
collection = await collector.collect(
    [("user", "Find five passages about patience")],
    goal=CollectionGoal(
        target_count=5,
        item_description="distinct passages that directly discuss patience",
        max_per_document=1,
        diversity_metadata_keys=("author_id",),
    ),
    includeRelationships=True,
    config=AgenticSearchConfig(max_iterations=4, token_budget=8_000),
)

for item in collection.items:
    # Every item is sliced from the original SearchResult text.
    print(item.text, item.source_id, item.start_offset, item.end_offset)

if not collection.complete:
    print("Verified partial result:", collection.stop_reason)

See AgenticCollection.md for provider hooks, security invariants, and the result contract.

Deep Research Pipeline

Learn how to customise the default prompts via maktaba_templates.md.

from maktaba.pipeline import create_deep_research_pipeline
from maktaba.embedding import OpenAIEmbedder
from maktaba.storage import QdrantStore
from maktaba.llm import OpenAILLM

pipeline = create_deep_research_pipeline(
    embedder=OpenAIEmbedder(api_key="..."),
    store=QdrantStore(url="http://localhost:6333", collection_name="docs"),
    llm=OpenAILLM(api_key="...", model="gpt-4o-mini"),
)

result = await pipeline.run_research("Impacts of lunar dust on spacecraft design")

chunks = [chunk async for chunk in result.stream]
print("".join(chunks))       # Final long-form report
print(result.queries_used)   # Queries issued during research
print(result.source_indices) # 1-based indices of retained sources

For a full walkthrough (configuration knobs, streaming, stage overrides), see docs/DeepResearch.md and examples/deep_research_pipeline.py.

Development

Running Checks Before Push

Before pushing to the remote repository, run all quality checks:

Linux/Mac/Git Bash:

./scripts/check.sh

Windows CMD:

scripts\check.bat

This will run:

  • Ruff linting
  • MyPy type checking
  • Pytest tests

All checks must pass before pushing.

Documentation

  • Overview: docs/Overview.md
  • Quickstart: docs/Quickstart.md
  • Pipelines: docs/Pipelines.md
  • Agentic Search v2: docs/AgenticV2.md
  • Verified evidence collection: docs/AgenticCollection.md
  • Providers: docs/Providers.md
  • Examples: docs/Examples.md
  • Troubleshooting: docs/Troubleshooting.md

Website (coming soon): maktaba.nuhatech.com

License

MIT License - see LICENSE

About NuhaTech

Built by NuhaTech - creators of Kutub and Muqabia.

Metadata

Release files for maktaba 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for maktaba 0.3.1
File Size Uploaded Provenance Actions
maktaba-0.3.1.tar.gz 553.0 kB With provenance Details for maktaba-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for maktaba 0.3.1
File Interpreter ABI Platform Actions
maktaba-0.3.1-py3-none-any.whl Python 3 none any Details for maktaba-0.3.1-py3-none-any.whl

Total release size: 650.0 kB

Release files / maktaba-0.3.1.tar.gz

Download URL maktaba-0.3.1.tar.gz
Size 553.0 kB
Tags Source
SHA-256 checksum
How to use checksums
7fe7f92d66e0105da5702336704d8f445535646b9b1ed384c0578bc2b48b524d
BLAKE2b-256 checksum
How to use checksums
7adc0e37e11ab9ccd7ea9f991dfcbbd4ce23bbd577d4809ecb886ff5c3629e40
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.

Transparency log

Release files / maktaba-0.3.1-py3-none-any.whl

Download URL maktaba-0.3.1-py3-none-any.whl
Size 97.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eff656cb0c21122f5f22026de53aebfafaa415c6a4c0772de40cdbeac58fad7d
BLAKE2b-256 checksum
How to use checksums
848378f99119a77b134912b59480cc130882dff465fd4158e34d450bd66c368b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.

Transparency log

Security for maktaba 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for maktaba-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page