Maktaba
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
Using UV (Recommended)
# 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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| maktaba-0.2.0.tar.gz | 541.3 kB | With provenance | Details for maktaba-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| maktaba-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for maktaba-0.2.0-py3-none-any.whl |
Total release size: 629.3 kB
Release files / maktaba-0.2.0.tar.gz
| Download URL | maktaba-0.2.0.tar.gz |
|---|---|
| Size | 541.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
38657597ec9d92106b746080de79db10a14212d942858eb569b5b1026eb13343
|
|
BLAKE2b-256 checksum How to use checksums |
1629090fb2aafcf38618dca4c8ef3370a8883166db26ce6fa4375b2f1abd7bd6
|
| 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 logRelease files / maktaba-0.2.0-py3-none-any.whl
| Download URL | maktaba-0.2.0-py3-none-any.whl |
|---|---|
| Size | 88.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aef2331e20a6d8dacdd94766ce5f69fd084bff62e17901192bde42452a25e715
|
|
BLAKE2b-256 checksum How to use checksums |
308f128299482c864a199c0474fac056af407c45caa5da24940bad1b8af5822f
|
| 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 logSecurity for maktaba 0.2.0
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.
Attestation for maktaba-0.2.0.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 logA 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.