odino 0.1.1

Local semantic search CLI tool for codebases using embeddings

Odino: Local Semantic Search CLI

A fast local semantic search tool that helps you find code using natural language queries. No internet required, everything runs locally using the embeddinggemma-300m model.

Quick Start

Install Odino directly from PyPI:

pip install odino

Or install from source:

git clone https://github.com/cesp99/odino.git
cd odino
pip install -e .

For detailed installation instructions, including uninstallation and troubleshooting, see INSTALL.md.

Usage

Index your codebase

# Index current directory
odino index .

# Index specific directory
odino index /path/to/project

# Index with custom model (optional)
odino index /path/to/project --model <your-own-model>

Search your code

# Basic search (returns 2 results by default)
odino -q "function that handles user authentication"

# Search with custom number of results
odino -q "database connection" -r 10

# Search specific file types
odino -q "error handling" --include "*.py"

Check status

odino status

Examples

Find authentication code:

odino -q "user login function"

Search for database queries:

odino -q "sql select statement" --include "*.sql"

Find error handling patterns:

odino -q "try catch exception handling"

Project Structure

odino/
├── odino/
│   ├── __init__.py
│   ├── cli.py              # CLI entry point
│   ├── indexer.py          # File indexing logic
│   ├── searcher.py         # Semantic search implementation
│   └── utils.py            # Utility functions
├── pyproject.toml          # Project configuration
├── README.md              # This file
└── .odinoignore           # Default ignore patterns

Configuration

Odino creates a .odino/ directory in your project root with:

• config.json - Configuration settings
• chroma_db/ - Vector database storage
• indexed_files.json - File tracking metadata

Default configuration:

{
  "model_name": "EmmanuelEA/eea-embedding-gemma",
  "chunk_size": 512,
  "chunk_overlap": 50,
  "max_results": 2,
  "embedding_batch_size": 32,
  "device_preference": "auto"
}

How It Works

1. Indexing: Scans your codebase, chunks files, and generates embeddings using the embeddinggemma-300m model
2. Storage: Saves embeddings locally in ChromaDB vector database
3. Search: Converts your natural language query to embeddings and finds semantically similar code
4. Results: Displays file paths, similarity scores, and code snippets

Features

• Local Processing: No internet required, everything runs offline
• Fast Indexing: embeddinggemma-300m model optimized for speed
• Smart Chunking: Handles large files by splitting into manageable chunks
• Beautiful Output: Rich console formatting with syntax highlighting
• Incremental Updates: Only reindexes changed files
• Flexible Filtering: Search by file type, limit results, custom patterns

Advanced Usage

Custom Ignore Patterns

Create a .odinoignore file in your project root:

# Ignore specific directories
build/
dist/
node_modules/

# Ignore file patterns
*.log
*.tmp
*.cache

Force Reindex

odino index . --force

Status Check

odino status

Troubleshooting

Model Download Issues

The embeddinggemma-300m model downloads automatically on first use. Ensure you have:

• Stable internet connection for initial download
• Sufficient disk space (~300MB for model)

Permission Errors

Make sure you have read permissions for files you want to index and write permissions for the .odino/ directory.

Memory Issues

For very large codebases, consider:

• Reducing chunk size in configuration
• Excluding large directories with .odinoignore
• Indexing in batches

MPS (Apple Silicon) Memory Issues

If you encounter MPS backend out of memory errors on Apple Silicon:

1. Reduce batch size in your .odino/config.json:

{
  "embedding_batch_size": 16,
  "device_preference": "auto"
}

2. Force CPU usage for stable processing:

{
  "device_preference": "cpu"
}

3. Use smaller batch sizes if memory issues persist:

{
  "embedding_batch_size": 8
}

The system automatically handles MPS memory management with:

• Automatic batch processing in configurable sizes
• MPS memory clearing after each batch
• Automatic CPU fallback when MPS runs out of memory
• Smart device selection based on availability

For advanced memory management configuration and more detailed troubleshooting, see MEMORY_MANAGEMENT.md.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the GNU General Public License v3.0 - see LICENSE file for details.

Acknowledgments

• Built with Typer for the CLI
• Uses Sentence Transformers for embeddings
• Powered by ChromaDB for vector storage
• Formatted with Rich for beautiful output