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 VoyageReranker

# Create pipeline
pipeline = QueryPipeline(
    embedder=OpenAIEmbedder(api_key="..."),
    vector_store=QdrantStore(url="http://localhost:6333", collection_name="docs"),
    reranker=VoyageReranker(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.2

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.2
File Size Uploaded Provenance Actions
maktaba-0.3.2.tar.gz 554.8 kB With provenance Details for maktaba-0.3.2.tar.gz

Built distribution (wheel)

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

Total release size: 653.8 kB

Release files / maktaba-0.3.2.tar.gz

Download URL maktaba-0.3.2.tar.gz
Size 554.8 kB
Tags Source
SHA-256 checksum
How to use checksums
3da27294d27aa8c49deebe72b13d4ce9e707c732b1515324ab3b980d8f48110d
BLAKE2b-256 checksum
How to use checksums
58580a892a521167b399863ff6e331b3470a509c121329e1401b425c5ab16a5e
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 29, 2026.

Transparency log

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

Download URL maktaba-0.3.2-py3-none-any.whl
Size 98.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
368fa87f0d0cb171206fc10d9596b1d87d963fac13ccb9c42c2a49e242a90124
BLAKE2b-256 checksum
How to use checksums
90215ab726311392db498c94a1cff531f764650a29ca51b789bd1fcbafac1eb9
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 29, 2026.

Transparency log

Security for maktaba 0.3.2

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.2.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 29, 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.2 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