# ContextLite Python Package
[](https://badge.fury.io/py/contextlite)
[](https://pypi.org/project/contextlite/)
[](https://opensource.org/licenses/MIT)
**RAG Systems Were a Mistake** - Replace slow vector databases with mathematically optimal context selection.
⚡ **0.3ms** response time (vs 30-50ms for vector DBs) | 🎯 **Provably optimal** results | 💰 **$0** ongoing costs | 🔒 **100% local**
A Python wrapper for [ContextLite](https://contextlite.com) - the context engine that makes vector databases obsolete. Perfect for RAG applications, document search, and AI context management.
**[⬇️ More Downloads & Platforms](https://huggingface.co/spaces/MikeKuykendall/contextlite-download)**
## 🚀 Quick Start
### Installation
```bash
pip install contextlite
```
### ⚡ Auto-Discovery Setup (NEW in v2.0)
```bash
# One command setup for all your repositories
contextlite --onboard
# ✅ Finds all Git repositories automatically
# ✅ Preserves existing ContextLite databases
# ✅ Configures optimal settings per project
# ✅ Sets up development tool integration
# ✅ Ready to use immediately
```
### Basic Usage
```python
from contextlite import ContextLiteClient
# Auto-start server and add documents
with ContextLiteClient() as client:
# Add some documents
client.add_document("The quick brown fox jumps over the lazy dog.", doc_id="doc1")
client.add_document("Python is a great programming language.", doc_id="doc2")
client.add_document("Machine learning is transforming software development.", doc_id="doc3")
# Query for relevant content
results = client.query("programming language")
print(f"Found {len(results['documents'])} relevant documents")
for doc in results['documents']:
print(f"Score: {doc['score']:.3f} - {doc['content'][:50]}...")
```
### Command Line Usage
The package also installs a `contextlite` command that acts as a wrapper for the native binary:
```bash
# Start ContextLite server
contextlite --port 8080
# Get help
contextlite --help
```
## 📋 Features
### 🆕 v2.0 Auto-Discovery Features
- **🔍 Intelligent Repository Detection**: Automatically finds all Git repositories
- **⚡ 30-Second Setup**: `contextlite --onboard` configures everything
- **🏗️ Multi-Project Management**: Independent ContextLite instances per project
- **🔌 Development Tool Integration**: Auto-imports from Git, VS Code, Claude Code, JetBrains
- **🛡️ Enterprise Security**: Production-ready with comprehensive security hardening
### Core Performance
- **🔥 Ultra-Fast**: Native Go binary performance with Python convenience
- **🛠️ Auto-Management**: Automatically detects, downloads, and manages ContextLite binary
- **🔌 Easy Integration**: Simple Python API with context manager support
- **🌍 Cross-Platform**: Works on Windows, macOS, and Linux (x64 and ARM64)
- **⚡ Zero Dependencies**: Core functionality requires only standard library (requests for auto-download)
## 🏗️ Architecture
This Python package is a "shim" that provides Python bindings for the high-performance ContextLite binary:
1. **Binary Detection**: Automatically finds ContextLite binary in PATH or common install locations
2. **Auto-Download**: Downloads appropriate binary for your platform if not found
3. **Server Management**: Optionally manages ContextLite server lifecycle
4. **Python API**: Provides convenient Python interface over REST API
## 📖 API Reference
### ContextLiteClient
The main interface for interacting with ContextLite.
#### Constructor
```python
ContextLiteClient(
host="localhost", # Server host
port=8080, # Server port
auto_start=True, # Auto-start server if not running
database_path=None, # Optional database file path
timeout=30.0 # Request timeout in seconds
)
```
#### Methods
- **`add_document(content, document_id=None, metadata=None)`** - Add a document
- **`query(query, max_results=None, min_score=None)`** - Search for documents
- **`get_document(document_id)`** - Retrieve specific document
- **`delete_document(document_id)`** - Delete a document
- **`get_stats()`** - Get server statistics
- **`is_server_running()`** - Check if server is responsive
### Context Manager
```python
from contextlite import contextlite_client
with contextlite_client(port=8080) as client:
client.add_document("Hello world!")
results = client.query("hello")
```
## 🔧 Binary Management
The package handles ContextLite binary management automatically:
### Detection Strategy
1. **PATH**: Checks if `contextlite` is in system PATH
2. **System Locations**: Common install directories (`/usr/local/bin`, Program Files, etc.)
3. **User Data**: User-specific data directory
4. **Package Data**: Bundled with package (if available)
### Auto-Download
If no binary is found, the package will:
1. Detect your platform and architecture
2. Download the appropriate binary from GitHub releases
3. Store it in user data directory
4. Make it executable and ready to use
### Manual Installation
You can also install ContextLite binary manually:
```bash
# Download from GitHub releases
curl -L https://github.com/Michael-A-Kuykendall/contextlite/releases/latest/download/contextlite_linux_amd64 -o contextlite
chmod +x contextlite
sudo mv contextlite /usr/local/bin/
```
## 🌐 Examples
### Document Management
```python
from contextlite import ContextLiteClient
client = ContextLiteClient()
# Add documents with metadata
client.add_document(
content="Advanced machine learning techniques for natural language processing.",
document_id="ml-nlp-guide",
metadata={
"category": "machine-learning",
"difficulty": "advanced",
"tags": ["nlp", "deep-learning", "transformers"]
}
)
# Query with filters
results = client.query(
query="natural language processing",
max_results=5,
min_score=0.7
)
for doc in results['documents']:
print(f"Document: {doc['id']}")
print(f"Score: {doc['score']:.3f}")
print(f"Content: {doc['content'][:100]}...")
print(f"Metadata: {doc.get('metadata', {})}")
print("-" * 50)
```
### Batch Operations
```python
from contextlite import ContextLiteClient
# Process multiple documents
documents = [
"Python is a versatile programming language.",
"JavaScript powers modern web development.",
"Go offers excellent performance for backend services.",
"Rust provides memory safety without garbage collection."
]
with ContextLiteClient() as client:
# Batch add documents
for i, content in enumerate(documents):
client.add_document(content, document_id=f"lang-{i}")
# Search across all documents
results = client.query("backend programming")
print(f"Found {len(results['documents'])} relevant documents")
for doc in results['documents']:
print(f"• {doc['content']} (Score: {doc['score']:.3f})")
```
### Custom Server Configuration
```python
from contextlite import ContextLiteClient
# Connect to existing server
client = ContextLiteClient(
host="remote-server.com",
port=9090,
auto_start=False # Don't try to start server
)
# Use custom database location
local_client = ContextLiteClient(
database_path="/path/to/my/database.db",
port=8081
)
```
## 🚨 Error Handling
```python
from contextlite import (
ContextLiteClient,
BinaryNotFoundError,
ServerError,
ContextLiteError
)
try:
with ContextLiteClient() as client:
results = client.query("test query")
except BinaryNotFoundError:
print("ContextLite binary not found. Please install it manually.")
except ServerError as e:
print(f"Server error: {e}")
except ContextLiteError as e:
print(f"ContextLite error: {e}")
```
## 🛠️ Development
### Local Development
```bash
# Clone the repository
git clone https://github.com/Michael-A-Kuykendall/contextlite.git
cd contextlite/python-wrapper
# Install in development mode
pip install -e .
# Install development dependencies
pip install -e .[dev]
# Run tests
pytest
# Format code
black contextlite/
isort contextlite/
# Type checking
mypy contextlite/
```
### Testing
```python
import pytest
from contextlite import ContextLiteClient
def test_basic_operations():
with ContextLiteClient() as client:
# Add document
response = client.add_document("Test content", doc_id="test1")
assert response['success'] == True
# Query
results = client.query("test")
assert len(results['documents']) > 0
# Cleanup
client.delete_document("test1")
```
## 📝 Requirements
- **Python**: 3.8+
- **Platform**: Windows, macOS, Linux (x64/ARM64)
- **Dependencies**: `requests`, `platformdirs`
- **ContextLite Binary**: Auto-downloaded or manually installed
## 📄 License
This Python package is released under the MIT License. The ContextLite binary may have different licensing terms.
## 🔗 Links
- **Homepage**: https://contextlite.com
- **Documentation**: https://docs.contextlite.com
- **GitHub**: https://github.com/Michael-A-Kuykendall/contextlite
- **PyPI**: https://pypi.org/project/contextlite/
- **Issues**: https://github.com/Michael-A-Kuykendall/contextlite/issues
## 💬 Support
- **GitHub Issues**: For bug reports and feature requests
- **Documentation**: Comprehensive guides and API reference
- **Community**: Join our Discord server for discussions
---
Built with ❤️ by the ContextLite team. Made for developers who need blazing-fast context retrieval.
Raw data
{
"_id": null,
"home_page": null,
"name": "contextlite",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "rag, vector-database-alternative, smt-optimization, context-engine, ai, retrieval, fast, local, zero-cost, optimal",
"author": null,
"author_email": "ContextLite Team <support@contextlite.com>",
"download_url": "https://files.pythonhosted.org/packages/6c/cf/943fc379cba9ac5f2663f517b938702cc64962834334d8e5040dc93de892/contextlite-2.0.7.tar.gz",
"platform": null,
"description": "# ContextLite Python Package\n\n[](https://badge.fury.io/py/contextlite)\n[](https://pypi.org/project/contextlite/)\n[](https://opensource.org/licenses/MIT)\n\n**RAG Systems Were a Mistake** - Replace slow vector databases with mathematically optimal context selection.\n\n\u26a1 **0.3ms** response time (vs 30-50ms for vector DBs) | \ud83c\udfaf **Provably optimal** results | \ud83d\udcb0 **$0** ongoing costs | \ud83d\udd12 **100% local**\n\nA Python wrapper for [ContextLite](https://contextlite.com) - the context engine that makes vector databases obsolete. Perfect for RAG applications, document search, and AI context management.\n\n**[\u2b07\ufe0f More Downloads & Platforms](https://huggingface.co/spaces/MikeKuykendall/contextlite-download)**\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install contextlite\n```\n\n### \u26a1 Auto-Discovery Setup (NEW in v2.0)\n\n```bash\n# One command setup for all your repositories\ncontextlite --onboard\n\n# \u2705 Finds all Git repositories automatically\n# \u2705 Preserves existing ContextLite databases\n# \u2705 Configures optimal settings per project\n# \u2705 Sets up development tool integration\n# \u2705 Ready to use immediately\n```\n\n### Basic Usage\n\n```python\nfrom contextlite import ContextLiteClient\n\n# Auto-start server and add documents\nwith ContextLiteClient() as client:\n # Add some documents\n client.add_document(\"The quick brown fox jumps over the lazy dog.\", doc_id=\"doc1\")\n client.add_document(\"Python is a great programming language.\", doc_id=\"doc2\")\n client.add_document(\"Machine learning is transforming software development.\", doc_id=\"doc3\")\n \n # Query for relevant content\n results = client.query(\"programming language\")\n print(f\"Found {len(results['documents'])} relevant documents\")\n \n for doc in results['documents']:\n print(f\"Score: {doc['score']:.3f} - {doc['content'][:50]}...\")\n```\n\n### Command Line Usage\n\nThe package also installs a `contextlite` command that acts as a wrapper for the native binary:\n\n```bash\n# Start ContextLite server\ncontextlite --port 8080\n\n# Get help\ncontextlite --help\n```\n\n## \ud83d\udccb Features\n\n### \ud83c\udd95 v2.0 Auto-Discovery Features\n- **\ud83d\udd0d Intelligent Repository Detection**: Automatically finds all Git repositories\n- **\u26a1 30-Second Setup**: `contextlite --onboard` configures everything\n- **\ud83c\udfd7\ufe0f Multi-Project Management**: Independent ContextLite instances per project\n- **\ud83d\udd0c Development Tool Integration**: Auto-imports from Git, VS Code, Claude Code, JetBrains\n- **\ud83d\udee1\ufe0f Enterprise Security**: Production-ready with comprehensive security hardening\n\n### Core Performance\n- **\ud83d\udd25 Ultra-Fast**: Native Go binary performance with Python convenience\n- **\ud83d\udee0\ufe0f Auto-Management**: Automatically detects, downloads, and manages ContextLite binary\n- **\ud83d\udd0c Easy Integration**: Simple Python API with context manager support\n- **\ud83c\udf0d Cross-Platform**: Works on Windows, macOS, and Linux (x64 and ARM64)\n- **\u26a1 Zero Dependencies**: Core functionality requires only standard library (requests for auto-download)\n\n## \ud83c\udfd7\ufe0f Architecture\n\nThis Python package is a \"shim\" that provides Python bindings for the high-performance ContextLite binary:\n\n1. **Binary Detection**: Automatically finds ContextLite binary in PATH or common install locations\n2. **Auto-Download**: Downloads appropriate binary for your platform if not found\n3. **Server Management**: Optionally manages ContextLite server lifecycle \n4. **Python API**: Provides convenient Python interface over REST API\n\n## \ud83d\udcd6 API Reference\n\n### ContextLiteClient\n\nThe main interface for interacting with ContextLite.\n\n#### Constructor\n\n```python\nContextLiteClient(\n host=\"localhost\", # Server host\n port=8080, # Server port \n auto_start=True, # Auto-start server if not running\n database_path=None, # Optional database file path\n timeout=30.0 # Request timeout in seconds\n)\n```\n\n#### Methods\n\n- **`add_document(content, document_id=None, metadata=None)`** - Add a document\n- **`query(query, max_results=None, min_score=None)`** - Search for documents\n- **`get_document(document_id)`** - Retrieve specific document\n- **`delete_document(document_id)`** - Delete a document\n- **`get_stats()`** - Get server statistics\n- **`is_server_running()`** - Check if server is responsive\n\n### Context Manager\n\n```python\nfrom contextlite import contextlite_client\n\nwith contextlite_client(port=8080) as client:\n client.add_document(\"Hello world!\")\n results = client.query(\"hello\")\n```\n\n## \ud83d\udd27 Binary Management\n\nThe package handles ContextLite binary management automatically:\n\n### Detection Strategy\n\n1. **PATH**: Checks if `contextlite` is in system PATH\n2. **System Locations**: Common install directories (`/usr/local/bin`, Program Files, etc.)\n3. **User Data**: User-specific data directory\n4. **Package Data**: Bundled with package (if available)\n\n### Auto-Download\n\nIf no binary is found, the package will:\n\n1. Detect your platform and architecture\n2. Download the appropriate binary from GitHub releases\n3. Store it in user data directory\n4. Make it executable and ready to use\n\n### Manual Installation\n\nYou can also install ContextLite binary manually:\n\n```bash\n# Download from GitHub releases\ncurl -L https://github.com/Michael-A-Kuykendall/contextlite/releases/latest/download/contextlite_linux_amd64 -o contextlite\nchmod +x contextlite\nsudo mv contextlite /usr/local/bin/\n```\n\n## \ud83c\udf10 Examples\n\n### Document Management\n\n```python\nfrom contextlite import ContextLiteClient\n\nclient = ContextLiteClient()\n\n# Add documents with metadata\nclient.add_document(\n content=\"Advanced machine learning techniques for natural language processing.\",\n document_id=\"ml-nlp-guide\",\n metadata={\n \"category\": \"machine-learning\",\n \"difficulty\": \"advanced\",\n \"tags\": [\"nlp\", \"deep-learning\", \"transformers\"]\n }\n)\n\n# Query with filters\nresults = client.query(\n query=\"natural language processing\",\n max_results=5,\n min_score=0.7\n)\n\nfor doc in results['documents']:\n print(f\"Document: {doc['id']}\")\n print(f\"Score: {doc['score']:.3f}\")\n print(f\"Content: {doc['content'][:100]}...\")\n print(f\"Metadata: {doc.get('metadata', {})}\")\n print(\"-\" * 50)\n```\n\n### Batch Operations\n\n```python\nfrom contextlite import ContextLiteClient\n\n# Process multiple documents\ndocuments = [\n \"Python is a versatile programming language.\",\n \"JavaScript powers modern web development.\", \n \"Go offers excellent performance for backend services.\",\n \"Rust provides memory safety without garbage collection.\"\n]\n\nwith ContextLiteClient() as client:\n # Batch add documents\n for i, content in enumerate(documents):\n client.add_document(content, document_id=f\"lang-{i}\")\n \n # Search across all documents\n results = client.query(\"backend programming\")\n \n print(f\"Found {len(results['documents'])} relevant documents\")\n for doc in results['documents']:\n print(f\"\u2022 {doc['content']} (Score: {doc['score']:.3f})\")\n```\n\n### Custom Server Configuration\n\n```python\nfrom contextlite import ContextLiteClient\n\n# Connect to existing server\nclient = ContextLiteClient(\n host=\"remote-server.com\",\n port=9090,\n auto_start=False # Don't try to start server\n)\n\n# Use custom database location\nlocal_client = ContextLiteClient(\n database_path=\"/path/to/my/database.db\",\n port=8081\n)\n```\n\n## \ud83d\udea8 Error Handling\n\n```python\nfrom contextlite import (\n ContextLiteClient, \n BinaryNotFoundError, \n ServerError,\n ContextLiteError\n)\n\ntry:\n with ContextLiteClient() as client:\n results = client.query(\"test query\")\n \nexcept BinaryNotFoundError:\n print(\"ContextLite binary not found. Please install it manually.\")\n \nexcept ServerError as e:\n print(f\"Server error: {e}\")\n \nexcept ContextLiteError as e:\n print(f\"ContextLite error: {e}\")\n```\n\n## \ud83d\udee0\ufe0f Development\n\n### Local Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/Michael-A-Kuykendall/contextlite.git\ncd contextlite/python-wrapper\n\n# Install in development mode\npip install -e .\n\n# Install development dependencies\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Format code\nblack contextlite/\nisort contextlite/\n\n# Type checking\nmypy contextlite/\n```\n\n### Testing\n\n```python\nimport pytest\nfrom contextlite import ContextLiteClient\n\ndef test_basic_operations():\n with ContextLiteClient() as client:\n # Add document\n response = client.add_document(\"Test content\", doc_id=\"test1\")\n assert response['success'] == True\n \n # Query\n results = client.query(\"test\")\n assert len(results['documents']) > 0\n \n # Cleanup\n client.delete_document(\"test1\")\n```\n\n## \ud83d\udcdd Requirements\n\n- **Python**: 3.8+ \n- **Platform**: Windows, macOS, Linux (x64/ARM64)\n- **Dependencies**: `requests`, `platformdirs`\n- **ContextLite Binary**: Auto-downloaded or manually installed\n\n## \ud83d\udcc4 License\n\nThis Python package is released under the MIT License. The ContextLite binary may have different licensing terms.\n\n## \ud83d\udd17 Links\n\n- **Homepage**: https://contextlite.com\n- **Documentation**: https://docs.contextlite.com \n- **GitHub**: https://github.com/Michael-A-Kuykendall/contextlite\n- **PyPI**: https://pypi.org/project/contextlite/\n- **Issues**: https://github.com/Michael-A-Kuykendall/contextlite/issues\n\n## \ud83d\udcac Support\n\n- **GitHub Issues**: For bug reports and feature requests\n- **Documentation**: Comprehensive guides and API reference\n- **Community**: Join our Discord server for discussions\n\n---\n\nBuilt with \u2764\ufe0f by the ContextLite team. Made for developers who need blazing-fast context retrieval.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "RAG Systems Were a Mistake - Replace vector databases with 0.3ms mathematically optimal context selection",
"version": "2.0.7",
"project_urls": {
"Bug Reports": "https://github.com/Michael-A-Kuykendall/contextlite/issues",
"Changelog": "https://github.com/Michael-A-Kuykendall/contextlite/releases",
"Documentation": "https://docs.contextlite.com",
"Homepage": "https://contextlite.com",
"Repository": "https://github.com/Michael-A-Kuykendall/contextlite"
},
"split_keywords": [
"rag",
" vector-database-alternative",
" smt-optimization",
" context-engine",
" ai",
" retrieval",
" fast",
" local",
" zero-cost",
" optimal"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c218548f162da265d1a66fb411854a14ec37e12515b0406e54b5d0ef8b014cfc",
"md5": "53dfc1f3465d243c15955f37d0bc2241",
"sha256": "6540843526aa87101129662982ad2e0648004ca4e2d0eb5b4e90a3aff159a573"
},
"downloads": -1,
"filename": "contextlite-2.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53dfc1f3465d243c15955f37d0bc2241",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12802,
"upload_time": "2025-09-01T22:14:33",
"upload_time_iso_8601": "2025-09-01T22:14:33.380837Z",
"url": "https://files.pythonhosted.org/packages/c2/18/548f162da265d1a66fb411854a14ec37e12515b0406e54b5d0ef8b014cfc/contextlite-2.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6ccf943fc379cba9ac5f2663f517b938702cc64962834334d8e5040dc93de892",
"md5": "5d9262989267a5f5f860f2b0871cf57a",
"sha256": "7d19c6ab987bf7b591085a3e6135cb28692e15ece6d0b2226facb5b0c4b484ea"
},
"downloads": -1,
"filename": "contextlite-2.0.7.tar.gz",
"has_sig": false,
"md5_digest": "5d9262989267a5f5f860f2b0871cf57a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15833,
"upload_time": "2025-09-01T22:14:34",
"upload_time_iso_8601": "2025-09-01T22:14:34.605862Z",
"url": "https://files.pythonhosted.org/packages/6c/cf/943fc379cba9ac5f2663f517b938702cc64962834334d8e5040dc93de892/contextlite-2.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 22:14:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Michael-A-Kuykendall",
"github_project": "contextlite",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "contextlite"
}
JSON
