contextly 0.1.7
AI Context Engine for Developers
Requires Python: >=3.9
Keywords: ai, analysis, code, context, development, documentation, llm

# 🧠 Contextly - The AI Context Engine for Developers

> "Know your code. Know your configs. Instantly."

Contextly is your terminal-native AI that helps you understand your codebase and configuration environment with natural-language queries and AI-powered explanations.

## 🎯 Features

- **Natural Language Queries**: Ask questions about your code in plain English
- **Configuration Management**: Compare and analyze config files (env, json, yaml, etc.)
- **Semantic Code Search**: Find relevant code snippets by describing what you're looking for
- **Offline Support**: Built-in local LLM integration with Ollama
- **Multi-Language Support**: Works with Python, JavaScript, TypeScript, and more
- **Privacy-Focused**: Your code never leaves your machine (when using local LLMs)
- **VSCode-Friendly**: All features work directly in your terminal or VS Code

## ⚡ Quick Start

1. **Installation**
   ```bash
   pip install contextly
   ```

2. **Setup (Optional)**
   ```bash
   # Configure local LLM (recommended)
   brew install ollama
   ollama pull codellama

   # Or set up OpenAI (optional)
   export OPENAI_API_KEY=your_api_key
   ```

3. **Initialize in Your Repo**
   ```bash
   cd your-project
   contextly sync
   ```

## 💡 Usage

### Ask Questions About Your Code

```bash
# General questions
contextly ask "How is user authentication handled?"
contextly ask "What's the database schema like?"

# Specific file questions
contextly ask "What does the login function in auth.py do?"

# Architecture questions
contextly ask "What's the overall project structure?"
```

### Search Code Semantically

```bash
# Find relevant code
contextly search "password hashing implementation"
contextly search "database connection setup"
```

### Analyze Specific Code

```bash
# Get explanation for code at a specific line
contextly explain src/auth.py:42

# Understand a function or class
contextly explain src/models.py:15
```

### Compare Config Files

```bash
# Compare different environment files
contextly diff .env.dev .env.prod

# Compare any config files
contextly diff config/local.yml config/prod.yml
```

## ⚙️ Configuration

Contextly can be configured via environment variables or a `contextly.yml` file in your project root:

```yaml
# contextly.yml
llm:
  provider: ollama  # or 'openai'
  model: codellama  # or 'gpt-4' for OpenAI
  temperature: 0.2

embedding:
  model: all-MiniLM-L6-v2  # Default embedding model
  cache_dir: .contextly    # Where to store the vector index

parsers:
  python:
    enabled: true
  javascript:
    enabled: true
  config:
    enabled: true
    extensions: ['.json', '.yml', '.yaml', '.env', '.toml']
```

### Environment Variables

- `CONTEXTLY_LLM_PROVIDER`: 'ollama' or 'openai'
- `CONTEXTLY_MODEL`: LLM model to use
- `OPENAI_API_KEY`: Required if using OpenAI
- `CONTEXTLY_CACHE_DIR`: Where to store the vector index

## �️ How It Works

Contextly works by:

1. **Parsing**: Analyzes your code and config files using language-specific parsers
2. **Embedding**: Creates vector embeddings of your code using SentenceTransformers
3. **Indexing**: Stores embeddings in a local ChromaDB for fast retrieval
4. **Reasoning**: Uses local or cloud LLMs to understand and explain code

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for:

- Setting up the development environment
- Running tests
- Code style guidelines
- Pull request process

## 📝 License

MIT License - see [LICENSE](LICENSE) for details.

## 🙋 FAQ

**Q: How does offline mode work?**  
A: When using Ollama as the LLM provider, all processing happens locally. Your code never leaves your machine.

**Q: What languages are supported?**  
A: Currently Python, JavaScript, TypeScript, and various config formats (JSON, YAML, TOML, ENV). More coming soon!

**Q: How can I customize the LLM responses?**  
A: Adjust the `temperature` setting in your config. Lower values (0.1-0.3) give more precise answers, higher values more creative ones.

**Q: Where is data stored?**  
A: By default, the vector index is stored in `.contextly/` in your project root. This can be configured via `CONTEXTLY_CACHE_DIR`.