contextly 0.1.0__tar.gz

contextly-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# 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 Environment
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Project specific
+.contextly/
+*.db
+embeddings/
+
+# Misc
+.DS_Store

contextly-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Contextly Team
+
+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.

contextly-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: contextly
+Version: 0.1.0
+Summary: AI Context Engine for Developers
+Project-URL: Homepage, https://github.com/contextly/contextly
+Project-URL: Repository, https://github.com/contextly/contextly
+Project-URL: Documentation, https://github.com/contextly/contextly#readme
+Project-URL: Bug Tracker, https://github.com/contextly/contextly/issues
+Author-email: Contextly Team <team@contextly.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,analysis,code,context,development,documentation,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: asyncio>=3.4.3
+Requires-Dist: cachetools>=5.3.2
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: huggingface-hub>=0.19.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: tiktoken>=0.5.1
+Requires-Dist: tokenizers>=0.15.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: tqdm>=4.66.1
+Requires-Dist: transformers>=4.35.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: black>=23.0.0; extra == 'test'
+Requires-Dist: isort>=5.12.0; extra == 'test'
+Requires-Dist: mypy>=1.5.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Requires-Dist: ruff>=0.1.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# 🧠 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`.

contextly-0.1.0/README.md

@@ -0,0 +1,150 @@
+# 🧠 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`.

contextly-0.1.0/pyproject.toml

@@ -0,0 +1,110 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "contextly"
+version = "0.1.0"
+authors = [
+    { name = "Contextly Team", email = "team@contextly.dev" },
+]
+description = "AI Context Engine for Developers"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["ai", "context", "code", "development", "llm", "documentation", "analysis"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Documentation",
+]
+
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "sentence-transformers>=2.2.0",
+    "chromadb>=0.4.0",
+    "pyyaml>=6.0.0",
+    "python-dotenv>=1.0.0",
+    "toml>=0.10.2",
+    "pydantic>=2.0.0",
+    "openai>=1.0.0",
+    "requests>=2.31.0",
+    "colorama>=0.4.6",
+    "aiohttp>=3.8.0",
+    "huggingface-hub>=0.19.0",
+    "tokenizers>=0.15.0",
+    "transformers>=4.35.0",
+    "asyncio>=3.4.3",
+    "aiosqlite>=0.19.0",
+    "tiktoken>=0.5.1",
+    "tqdm>=4.66.1",
+    "cachetools>=5.3.2",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "mypy>=1.5.0",
+    "ruff>=0.1.0",
+]
+
+dev = [
+    "pre-commit>=3.3.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "mypy>=1.5.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+contextly = "contextly.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/contextly/contextly"
+Repository = "https://github.com/contextly/contextly"
+Documentation = "https://github.com/contextly/contextly#readme"
+"Bug Tracker" = "https://github.com/contextly/contextly/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "--cov=contextly --cov-report=term-missing"
+
+[tool.black]
+line-length = 100
+target-version = ['py39']
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+line_length = 100
+multi_line_output = 3
+
+[tool.mypy]
+python_version = "3.9"
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unused_ignores = true
+warn_unused_configs = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+select = ["E", "F", "B", "I", "UP"]

contextly-0.1.0/src/contextly/__init__.py

@@ -0,0 +1,5 @@
+"""
+Contextly - The AI Context Engine for Developers
+"""
+
+__version__ = "0.1.0"

contextly-0.1.0/src/contextly/app.py

@@ -0,0 +1,85 @@
+"""
+Core business logic for Contextly commands.
+"""
+
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+from .core.analyzer import CodeAnalyzer
+from .core.embeddings import EmbeddingEngine
+from .core.sync import RepoSync
+from .llm.manager import LLMManager
+
+class Contextly:
+    """Main class coordinating Contextly's functionality."""
+    
+    def __init__(self, repo_path: Optional[Path] = None, model: Optional[str] = None):
+        self.repo_path = repo_path or Path.cwd()
+        self.llm_manager = LLMManager(model)
+        self.analyzer = CodeAnalyzer(self.repo_path)
+        self.embedding_engine = EmbeddingEngine(self.repo_path)
+        self.repo_sync = RepoSync(self.repo_path)
+        
+    def ask(self, question: str) -> Dict[str, Any]:
+        """Answer questions about the codebase."""
+        # Initialize if needed
+        if not hasattr(self, '_initialized'):
+            self.embedding_engine.initialize()
+            self._initialized = True
+            
+        # Search for relevant code
+        search_results = self.embedding_engine.search(question)
+        
+        # Build context from search results
+        context = []
+        for result in search_results['results']:
+            context.append(f"From {result['file']}:\n{result['content']}\n")
+            
+        # Generate answer using LLM
+        prompt = f"Question: {question}\n\nContext from codebase:\n{''.join(context)}\n\nAnswer:"
+        answer = self.analyzer.llm.generate(prompt)
+        
+        return {
+            'answer': answer,
+            'context': search_results
+        }
+        
+    def explain(self, location: str) -> str:
+        """Explain code at specific location."""
+        file_path, line_number = location.split(':')
+        return self.analyzer.explain_code(file_path, int(line_number))
+        
+    def search(self, term: str) -> Dict[str, Any]:
+        """Semantic search across codebase."""
+        if not hasattr(self, '_initialized'):
+            self.embedding_engine.initialize()
+            self._initialized = True
+            
+        results = self.embedding_engine.search(term)
+        return {
+            'query': results['query'],
+            'results': results['results']
+        }
+        
+    def diff(self, path1: Path, path2: Path) -> Dict[str, Any]:
+        """Compare configuration files."""
+        return self.analyzer.compare_configs(path1, path2)
+        
+    def sync(self) -> None:
+        """Build or rebuild the embedding index."""
+        # Scan repository
+        files = list(self.repo_sync.scan_files())
+        
+        # Build index
+        index = self.repo_sync.index_repository()
+        
+        # Initialize embedding engine
+        self.embedding_engine.initialize()
+        
+        # Convert index to list of documents
+        docs = []
+        for file_path, file_data in index.items():
+            docs.extend(file_data.get('chunks', []))
+            
+        # Embed documents
+        self.embedding_engine.embed_documents(docs)