maktaba 0.1.0__tar.gz

maktaba-0.1.0/.env.example

@@ -0,0 +1,30 @@
+# Maktaba environment variables (copy to .env and edit values)
+
+# OpenAI embeddings (required for examples using OpenAIEmbedder)
+OPENAI_API_KEY=sk-your-openai-key
+
+# Qdrant connection
+# Use ":memory:" for in-memory testing (no server required)
+# Or set to your server, e.g., "http://localhost:6333" or Qdrant Cloud URL
+QDRANT_URL=:memory:
+
+# Optional: Qdrant API key (for Qdrant Cloud)
+QDRANT_API_KEY=
+
+# Cohere Reranker (optional). If set, examples can enable API reranking.
+COHERE_API_KEY=
+
+# Logging level for pipelines (DEBUG, INFO, WARNING, ERROR)
+MAKTABA_LOG_LEVEL=INFO
+
+# Pinecone (optional)
+PINECONE_API_KEY=
+PINECONE_INDEX=
+
+# Chroma (optional)
+# If set, Chroma will persist data to this directory; otherwise in-memory
+CHROMA_PERSIST_DIR=
+
+# Weaviate (optional)
+WEAVIATE_URL=
+WEAVIATE_API_KEY=

maktaba-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Sync dependencies
+        run: |
+          uv sync --dev --all-extras
+
+      - name: Lint with ruff
+        run: |
+          uv run ruff check .
+
+      - name: Type check with mypy
+        run: |
+          uv run mypy src/maktaba --no-error-summary 2>&1 | tee mypy.log || true
+          ERROR_COUNT=$(grep -c "error:" mypy.log || echo 0)
+          echo "MyPy found $ERROR_COUNT errors"
+          # Fail if errors exceed threshold (allow third-party type stub issues)
+          if [ "$ERROR_COUNT" -gt 20 ]; then
+            echo "Too many type errors (threshold: 20)"
+            exit 1
+          fi
+
+      - name: Run tests
+        env:
+          PYTHONPATH: src
+        run: |
+          uv run pytest -q
+

maktaba-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,74 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write  # Required for trusted publishing
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/maktaba
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/maktaba
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

maktaba-0.1.0/.github/workflows/test-build.yml

@@ -0,0 +1,42 @@
+name: Test Build
+
+on:
+  pull_request:
+    branches: [ main, master ]
+  push:
+    branches: [ main, master ]
+
+jobs:
+  build:
+    name: Verify package builds
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Check build artifacts
+        run: |
+          ls -lh dist/
+          echo "Build artifacts created successfully"
+
+      - name: Install from wheel
+        run: |
+          python -m venv .test-venv
+          .test-venv/bin/pip install dist/*.whl
+
+      - name: Test import
+        run: |
+          .test-venv/bin/python -c "import maktaba; print(f'Successfully imported maktaba {maktaba.__version__}')"

maktaba-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Environment
+.env
+.env.local
+*.env
+
+# OS
+.DS_Store
+Thumbs.db

maktaba-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

maktaba-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project setup
+
+## [0.1.0] - YYYY-MM-DD
+
+### Added
+- Query pipeline with automatic reranking and citation formatting
+- Ingestion pipeline for document processing
+- Provider-agnostic embedding support (OpenAI, Azure, Cohere, Voyage)
+- Vector store integrations (Qdrant, Pinecone, Chroma, Redis)
+- Unstructured document chunking via LlamaIndex
+- Cohere reranking support
+- Async-first API design
+- Full type hints and Pydantic validation
+- Comprehensive test coverage
+- Arabic and multilingual language support
+
+### Documentation
+- Overview, quickstart, and provider guides
+- Example scripts for common use cases
+- API reference documentation
+
+[Unreleased]: https://github.com/nuhatech/maktaba/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nuhatech/maktaba/releases/tag/v0.1.0

maktaba-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NuhaTech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maktaba-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: maktaba
+Version: 0.1.0
+Summary: Production-ready RAG infrastructure for Arabic & multilingual applications
+Project-URL: Homepage, https://github.com/nuhatech/maktaba
+Project-URL: Documentation, https://maktaba.nuhatech.com
+Project-URL: Repository, https://github.com/nuhatech/maktaba
+Project-URL: Issues, https://github.com/nuhatech/maktaba/issues
+Author-email: NuhaTech <contact@nuhatech.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,embeddings,llm,rag,retrieval,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tenacity>=8.0
+Provides-Extra: all
+Requires-Dist: azure-ai-inference>=1.0.0b9; extra == 'all'
+Requires-Dist: chromadb>=0.4; extra == 'all'
+Requires-Dist: cohere>=5.0; extra == 'all'
+Requires-Dist: llama-index-core>=0.12; extra == 'all'
+Requires-Dist: llama-index-readers-file>=0.4; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: pinecone-client>=3.0; extra == 'all'
+Requires-Dist: python-magic>=0.4; extra == 'all'
+Requires-Dist: qdrant-client>=1.11; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: unstructured[all-docs]>=0.16; extra == 'all'
+Requires-Dist: voyageai>=0.2; extra == 'all'
+Provides-Extra: azure
+Requires-Dist: azure-ai-inference>=1.0.0b9; extra == 'azure'
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.4; extra == 'chroma'
+Provides-Extra: cohere
+Requires-Dist: cohere>=5.0; extra == 'cohere'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: pinecone
+Requires-Dist: pinecone-client>=3.0; extra == 'pinecone'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.11; extra == 'qdrant'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: unstructured
+Requires-Dist: llama-index-core>=0.12; extra == 'unstructured'
+Requires-Dist: llama-index-readers-file>=0.4; extra == 'unstructured'
+Requires-Dist: python-magic-bin>=0.4; (platform_system == 'Windows') and extra == 'unstructured'
+Requires-Dist: python-magic>=0.4; (platform_system != 'Windows') and extra == 'unstructured'
+Requires-Dist: unstructured[all-docs]>=0.16; extra == 'unstructured'
+Provides-Extra: voyage
+Requires-Dist: voyageai>=0.2; extra == 'voyage'
+Description-Content-Type: text/markdown
+
+# Maktaba
+
+[![CI](https://github.com/nuhatech/maktaba/actions/workflows/ci.yml/badge.svg)](https://github.com/nuhatech/maktaba/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/maktaba.svg)](https://badge.fury.io/py/maktaba)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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
+
+## Installation
+
+### Using UV (Recommended)
+
+```bash
+# 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
+
+```bash
+# Basic installation
+pip install maktaba
+
+# With OpenAI + Qdrant
+pip install "maktaba[openai,qdrant]"
+
+# With all providers
+pip install "maktaba[all]"
+```
+
+## Quick Start
+
+```python
+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}, ...]
+```
+
+## Documentation
+
+- Overview: docs/Overview.md
+- Quickstart: docs/Quickstart.md
+- Pipelines: docs/Pipelines.md
+- Providers: docs/Providers.md
+- Examples: docs/Examples.md
+- Troubleshooting: docs/Troubleshooting.md
+
+Website (coming soon): maktaba.nuhatech.com
+
+## License
+
+MIT License - see [LICENSE](LICENSE)
+
+## About NuhaTech
+
+Built by [NuhaTech](https://nuhatech.com) - creators of Kutub and Muqabia.

maktaba-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Maktaba
+
+[![CI](https://github.com/nuhatech/maktaba/actions/workflows/ci.yml/badge.svg)](https://github.com/nuhatech/maktaba/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/maktaba.svg)](https://badge.fury.io/py/maktaba)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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
+
+## Installation
+
+### Using UV (Recommended)
+
+```bash
+# 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
+
+```bash
+# Basic installation
+pip install maktaba
+
+# With OpenAI + Qdrant
+pip install "maktaba[openai,qdrant]"
+
+# With all providers
+pip install "maktaba[all]"
+```
+
+## Quick Start
+
+```python
+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}, ...]
+```
+
+## Documentation
+
+- Overview: docs/Overview.md
+- Quickstart: docs/Quickstart.md
+- Pipelines: docs/Pipelines.md
+- Providers: docs/Providers.md
+- Examples: docs/Examples.md
+- Troubleshooting: docs/Troubleshooting.md
+
+Website (coming soon): maktaba.nuhatech.com
+
+## License
+
+MIT License - see [LICENSE](LICENSE)
+
+## About NuhaTech
+
+Built by [NuhaTech](https://nuhatech.com) - creators of Kutub and Muqabia.

maktaba-0.1.0/docs/Examples.md

@@ -0,0 +1,9 @@
+% Examples
+
+- `examples/basic_usage.py` — embeddings + vector search
+- `examples/query_pipeline.py` — QueryPipeline with reranking + citations
+- `examples/ingestion_pipeline.py` — IngestionPipeline + QueryPipeline
+
+Tips
+- Set `OPENAI_API_KEY` to run OpenAI embedder
+- Use `url=":memory:"` for Qdrant in-memory testing

maktaba-0.1.0/docs/Overview.md

@@ -0,0 +1,9 @@
+% Maktaba Overview
+
+Maktaba is a production‑ready RAG library for Arabic & multilingual applications.
+
+- Vector store–friendly API (camelCase params, namespaces)
+- Embedding providers with batch‑first, async interfaces
+- Document chunking via Unstructured/LlamaIndex
+- QueryPipeline: retrieve → optional rerank → citations
+- IngestionPipeline: chunk → embed → upsert

maktaba-0.1.0/docs/Pipelines.md

@@ -0,0 +1,13 @@
+% Pipelines
+
+QueryPipeline
+- Embeds the query (input_type="query")
+- Retrieves from store (camelCase: topK, includeMetadata, namespace)
+- Optional rerank step (e.g., CohereReranker)
+- Formats citations into `[n]:` blocks
+
+IngestionPipeline
+- Chunk (text/file/url) via a BaseChunker (UnstructuredChunker)
+- Embed chunks in batches (input_type="document")
+- Upsert as `{doc_id}#chunk_{i}` ids
+- Optional on_progress callback

maktaba-0.1.0/docs/Providers.md

@@ -0,0 +1,12 @@
+% Providers
+
+Embedders
+- OpenAI (implemented): `maktaba.embedding.openai.OpenAIEmbedder`
+- Others can be added by subclassing `BaseEmbedder`
+
+Vector Stores
+- Qdrant (implemented): `maktaba.storage.qdrant.QdrantStore`
+- Pinecone/Weaviate/Chroma stubs exist; interface follows BaseVectorStore
+
+Rerankers
+- CohereReranker with offline heuristic by default

maktaba-0.1.0/docs/Quickstart.md

@@ -0,0 +1,35 @@
+% Quickstart
+
+Install with UV:
+
+```bash
+cd maktaba
+uv sync --extra openai --extra qdrant
+```
+
+Basic usage:
+
+```python
+from maktaba.embedding import OpenAIEmbedder
+from maktaba.storage import QdrantStore
+from maktaba.models import VectorChunk
+
+embedder = OpenAIEmbedder(api_key="sk-...", model="text-embedding-3-large")
+store = QdrantStore(url=":memory:", collection_name="demo")
+store.create_collection(dimension=embedder.dimension)
+
+vectors = await embedder.embed_batch(["hello", "world"], input_type="document")
+chunks = [VectorChunk(id=f"doc#chunk_{i}", vector=vectors[i], metadata={"text": t}) for i, t in enumerate(["hello","world"])]
+await store.upsert(chunks)
+```
+
+Query pipeline:
+
+```python
+from maktaba.pipeline.query import QueryPipeline
+from maktaba.reranking.cohere import CohereReranker
+
+pipeline = QueryPipeline(embedder, store, reranker=CohereReranker(use_api=False))
+result = await pipeline.search("hello", rerank=True)
+print(result["formatted_context"])  # [1]: ...
+```

maktaba-0.1.0/docs/Troubleshooting.md

@@ -0,0 +1,15 @@
+% Troubleshooting
+
+Pydantic UnsupportedFieldAttributeWarning
+- Emitted by a dependency; harmless.
+- Suppress if desired:
+  - `import warnings; warnings.filterwarnings("ignore", message=".*validate_default.*")`
+
+"libmagic is unavailable"
+- Improves filetype detection for Unstructured.
+- Windows: `uv pip install python-magic-bin`
+- Debian/Ubuntu: `apt-get install libmagic1` and `uv pip install python-magic`
+
+"'doc_id' is deprecated and 'id_' will be used instead"
+- LlamaIndex info; safe to ignore.
+- Suppress: `logging.getLogger("llama_index").setLevel(logging.ERROR)`