Metadata-Version: 2.4
Name: llamadb-llamasearch
Version: 0.1.0
Summary: Next-Gen Hybrid Python/Rust Data Platform with MLX
Home-page: https://llamasearch.ai
Author: LlamaSearch AI
Author-email: llamadb-llamasearch <nikjois@llamasearch.ai>
License: Apache-2.0
Project-URL: Homepage, https://github.com/yourusername/llamadb
Project-URL: Documentation, https://github.com/yourusername/llamadb#readme
Project-URL: Repository, https://github.com/yourusername/llamadb.git
Project-URL: Issues, https://github.com/yourusername/llamadb/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: scikit-learn>=1.2.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.6.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: tqdm>=4.66.0
Provides-Extra: api
Requires-Dist: fastapi>=0.115.0; extra == "api"
Requires-Dist: uvicorn>=0.27.0; extra == "api"
Requires-Dist: pydantic>=2.5.0; extra == "api"
Requires-Dist: starlette>=0.35.0; extra == "api"
Requires-Dist: httpx>=0.25.0; extra == "api"
Provides-Extra: dev
Requires-Dist: black>=23.10.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.6.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: ipython>=8.16.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.4.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.2.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "docs"
Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Provides-Extra: mlx
Requires-Dist: mlx>=0.5.0; extra == "mlx"
Provides-Extra: full
Requires-Dist: llamadb[api,dev,docs,mlx,test]; extra == "full"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# LlamaDB

High-performance vector database optimized for AI workloads with MLX acceleration for Apple Silicon.

![LlamaDB Logo](docs/assets/llamadb_logo.png)

## Overview

LlamaDB is a next-generation vector database designed for AI applications with a focus on performance, ease of use, and platform-specific optimizations. It provides:

- 🚀 **High-performance vector search** - Fast similarity search for embeddings
- 🍎 **MLX acceleration** - Up to 10x speedup on Apple Silicon devices
- 🦀 **Rust extensions** - Critical paths implemented in Rust for maximum performance
- 🐍 **Python-first API** - Simple, intuitive API with Python at its core
- 🔌 **REST API** - Easy integration with any language or framework

## Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/llamadb.git
cd llamadb

# Set up development environment
./setup_dev_environment.sh

# Activate the virtual environment
source .venv/bin/activate
```

### Run the Quickstart Demo

```bash
python quickstart.py
```

This will demonstrate basic vector operations, similarity search, and performance benchmarks.

### Start the API Server

```bash
# Start the server
python api_launcher.py --start

# Check status
python api_launcher.py --status

# Stop the server
python api_launcher.py --stop
```

## Core Features

### Vector Index

The `VectorIndex` class provides efficient similarity search:

```python
from llamadb.core import VectorIndex

# Create a new index with 128-dimensional vectors
index = VectorIndex(dimension=128)

# Add vectors with metadata
index.add_item(embedding, {"id": 1, "text": "Document content", "category": "Technology"})

# Search for similar vectors
results = index.search(query_vector, k=10)
```

### Accelerated Operations

LlamaDB provides optimized vector operations:

```python
from llamadb.core import cosine_similarity, l2_distance, dot_product

# Calculate similarity between vectors
similarity = cosine_similarity(vector_a, vector_b)
distance = l2_distance(vector_a, vector_b)
dot = dot_product(vector_a, vector_b)
```

### MLX Acceleration

On Apple Silicon devices, LlamaDB automatically uses MLX for acceleration:

```python
from llamadb.core import is_mlx_available, is_apple_silicon

if is_apple_silicon():
    print("Running on Apple Silicon")
    
if is_mlx_available():
    print("MLX acceleration is available")
```

## Development

For development instructions, see [DEVELOPER.md](./DEVELOPER.md).

### Utility Scripts

LlamaDB includes several utility scripts:

```bash
# Setup development environment
./setup_dev_environment.sh

# Run comprehensive tests
python test_llamadb.py --benchmark --plot

# Manage API server
python api_launcher.py --start
```

### Command Line Utilities

The `commands.sh` script provides common operations:

```bash
# Show help information
./commands.sh help

# Set up development environment
./commands.sh setup

# Run tests
./commands.sh test

# Run benchmarks
./commands.sh benchmark

# Run quickstart demo
./commands.sh quickstart
```

## API Server

LlamaDB includes a REST API server for language-agnostic access:

### Start the server

```bash
python api_launcher.py --start
```

### API Endpoints

- `GET /health` - Health check
- `GET /system` - System information
- `GET /index` - Index information
- `POST /search` - Search for similar vectors

Example search request:

```json
{
  "vector": [0.1, 0.2, 0.3, ...],
  "k": 10
}
```

## Performance

LlamaDB is designed for performance:

| Operation | NumPy | MLX (Apple Silicon) | Speedup |
|-----------|-------|---------------------|---------|
| Cosine Similarity | 5µs | 0.5µs | 10x |
| Matrix Multiply (1000x1000) | 50ms | 5ms | 10x |
| Search (10k vectors) | 10ms | 1ms | 10x |

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgements

- [MLX](https://github.com/ml-explore/mlx) - For the Apple Silicon acceleration
- [NumPy](https://numpy.org/) - For fundamental array operations
- [FastAPI](https://fastapi.tiangolo.com/) - For the REST API server
