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

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.

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
  • 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.2.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.2.1
File Size Uploaded Provenance Actions
maktaba-0.2.1.tar.gz 542.0 kB With provenance Details for maktaba-0.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 630.1 kB

Release files / maktaba-0.2.1.tar.gz

Download URL maktaba-0.2.1.tar.gz
Size 542.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a9050a8d5b51f7c546b27c6e52deaf5454cd5f69d10925a350d08afc7a698480
BLAKE2b-256 checksum
How to use checksums
a12ccb7ae8de308e3b2fe4ada9bd95da0763870a3859dffbc4945f273199071e
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 6, 2026.

Transparency log

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

Download URL maktaba-0.2.1-py3-none-any.whl
Size 88.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
823d0e25802928370b8746d903bed0f23357b2291747e5ea62e080172885334a
BLAKE2b-256 checksum
How to use checksums
a0b3632e59069283261a67468672ae6eb16ec4f411128b554b4c644edd1ce871
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 6, 2026.

Transparency log

Security for maktaba 0.2.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.2.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 6, 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.2.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