# **tenets**
<a href="https://tenets.dev"><img src="https://raw.githubusercontent.com/jddunn/tenets/master/docs/logos/tenets_dark_icon_transparent.png" alt="tenets logo" width="140" /></a>
**context that feeds your prompts.**
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://pypi.org/project/tenets/)
[](https://github.com/jddunn/tenets/actions/workflows/ci.yml)
[](https://codecov.io/gh/jddunn/tenets)
[](https://tenets.dev/docs)
**tenets** automatically finds and builds the most relevant context from your codebase. Instead of manually copying files or searching for documentation, tenets intelligently aggregates exactly what you need for debugging, building features, or chatting with AI assistants.
## What is tenets?
Intelligent context aggregation that:
- **Finds** all relevant files automatically
- **Ranks** them by importance using multiple factors
- **Aggregates** them within your token budget
- **Formats** perfectly for any use case
- **Pins** critical files per session for guaranteed inclusion
- **Injects** your tenets (guiding principles) into session interactions automatically in prompts
- **Transforms** content on demand (strip comments, condense whitespace, or force full raw context)
## Installation
```bash
# Core features only - lightweight, no ML dependencies
pip install tenets
# Add specific features
pip install tenets[light] # Adds keyword extraction & BM25/TF-IDF ranking
pip install tenets[viz] # Adds visualization capabilities
pip install tenets[ml] # Adds deep learning models (2GB+)
pip install tenets[all] # Everything
```
**Python 3.13 Note:** Compatible but some ML features have limitations. Use Python 3.12 for full ML support.
## Quick Start
### Three Ranking Modes
Tenets offers three modes that balance speed vs. accuracy for both `distill` and `rank` commands:
| Mode | Speed | Accuracy | Use Case | What It Does |
| ------------ | ----------- | -------- | ------------------------ | ------------------------------------------------------------ |
| **fast** | Fastest | Good | Quick exploration | Keyword & path matching, basic relevance |
| **balanced** | 1.5x slower | Better | Most use cases (default) | BM25 scoring, keyword extraction, structure analysis |
| **thorough** | 4x slower | Best | Complex refactoring | ML semantic similarity, pattern detection, dependency graphs |
### Core Commands
#### `distill` - Build Context with Content
```bash
# Basic usage - finds and aggregates relevant files
tenets distill "implement OAuth2" # Searches current directory by default
# Search specific directory
tenets distill "implement OAuth2" ./src
# Copy to clipboard (great for AI chats)
tenets distill "fix payment bug" --copy
# Generate interactive HTML report
tenets distill "analyze auth flow" --format html -o report.html
# Speed/accuracy trade-offs
tenets distill "debug issue" --mode fast # <5s, keyword matching
tenets distill "refactor API" --mode thorough # Semantic analysis
# Transform content to save tokens
tenets distill "review code" --remove-comments --condense
```
#### `rank` - Preview Files Without Content
```bash
# See what files would be included (much faster than distill!)
tenets rank "implement payments" --top 20 # Searches current directory by default
# Understand WHY files are ranked
tenets rank "fix auth" --factors
# Tree view for structure understanding
tenets rank "add caching" --tree --scores
# Export for automation
tenets rank "database migration" --format json | jq '.files[].path'
# Search specific directory
tenets rank "payment refactoring" ./src --top 10
```
### Sessions & Persistence
```bash
# Create a working session
tenets session create payment-feature
# Pin critical files for the session
tenets instill --session payment-feature --add-file src/core/payment.py
# Add guiding principles (tenets)
tenets tenet add "Always validate inputs" --priority critical
tenets instill --session payment-feature
# Build context using the session
tenets distill "add refund flow" --session payment-feature
```
### Other Commands
```bash
# Visualize architecture
tenets viz deps --output architecture.svg # Dependency graph
tenets viz deps --format html -o deps.html # Interactive HTML
# Track development patterns
tenets chronicle --since "last week" # Git activity
tenets momentum --team # Sprint velocity
# Analyze codebase
tenets examine . --complexity --threshold 10 # Find complex code
```
## Configuration
Create `.tenets.yml` in your project:
```yaml
ranking:
algorithm: balanced # fast | balanced | thorough
threshold: 0.1
use_git: true # Use git signals for relevance
context:
max_tokens: 100000
output:
format: markdown
copy_on_distill: true # Auto-copy to clipboard
ignore:
- vendor/
- '*.generated.*'
```
## Documentation
- **[Full Documentation](https://tenets.dev/docs)** - Complete guide and API reference
- **[CLI Reference](docs/CLI.md)** - All commands and options
- **[Configuration Guide](docs/CONFIG.md)** - Detailed configuration options
- **[Architecture Overview](docs/ARCHITECTURE.md)** - How tenets works internally
### Smart Summarization
When files exceed token budgets, tenets intelligently preserves:
- Function/class signatures
- Import statements
- Complex logic blocks
- Documentation and comments
- Recent changes
For more details on the summarization system, see [Architecture Documentation](docs/ARCHITECTURE.md).
## Advanced Features
### Test File Handling
Tests are **excluded by default** for most prompts, **automatically included** when your prompt mentions testing:
```bash
# Tests excluded (better context):
tenets distill "explain auth flow"
# Tests included (detected by intent):
tenets distill "write tests for auth"
tenets distill "fix failing tests"
# Manual override:
tenets distill "review code" --include-tests
tenets distill "fix test_user.py" --exclude-tests
```
### Output Formats
```bash
# Markdown (default, optimized for AI)
tenets distill "implement OAuth2" --format markdown
# Interactive HTML with search, charts, copy buttons
tenets distill "review API" --format html -o report.html
# JSON for programmatic use
tenets distill "analyze" --format json | jq '.files[0]'
# XML optimized for Claude
tenets distill "debug issue" --format xml
```
## Python API
```python
from tenets import Tenets
# Initialize
tenets = Tenets()
# Basic usage
result = tenets.distill("implement user authentication")
print(f"Generated {result.token_count} tokens")
# Rank files without content
from tenets.core.ranking import RelevanceRanker
ranker = RelevanceRanker(algorithm="balanced")
ranked_files = ranker.rank(files, prompt_context, threshold=0.1)
for file in ranked_files[:10]:
print(f"{file.path}: {file.relevance_score:.3f}")
```
## Supported Languages
Specialized analyzers for Python, JavaScript/TypeScript, Go, Java, C/C++, Ruby, PHP, Rust, and more. Configuration and documentation files are analyzed with smart heuristics for YAML, TOML, JSON, Markdown, etc.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
MIT License - see [LICENSE](LICENSE) for details.
---
## Contact
team@tenets.dev // team@manic.agency
Raw data
{
"_id": null,
"home_page": null,
"name": "tenets",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, code-analysis, code-intelligence, context-management, developer-tools, llm, prompt-engineering",
"author": null,
"author_email": "Tenets Team <team@tenets.dev>",
"download_url": "https://files.pythonhosted.org/packages/5f/3d/525cd9ad48146896c1eb2406b2e8497e802c9f54b73203ce7a71112c0307/tenets-0.3.2.tar.gz",
"platform": null,
"description": "# **tenets**\n\n<a href=\"https://tenets.dev\"><img src=\"https://raw.githubusercontent.com/jddunn/tenets/master/docs/logos/tenets_dark_icon_transparent.png\" alt=\"tenets logo\" width=\"140\" /></a>\n\n**context that feeds your prompts.**\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://pypi.org/project/tenets/)\n[](https://github.com/jddunn/tenets/actions/workflows/ci.yml)\n[](https://codecov.io/gh/jddunn/tenets)\n[](https://tenets.dev/docs)\n\n**tenets** automatically finds and builds the most relevant context from your codebase. Instead of manually copying files or searching for documentation, tenets intelligently aggregates exactly what you need for debugging, building features, or chatting with AI assistants.\n\n## What is tenets?\n\nIntelligent context aggregation that:\n\n- **Finds** all relevant files automatically\n- **Ranks** them by importance using multiple factors\n- **Aggregates** them within your token budget\n- **Formats** perfectly for any use case\n- **Pins** critical files per session for guaranteed inclusion\n- **Injects** your tenets (guiding principles) into session interactions automatically in prompts\n- **Transforms** content on demand (strip comments, condense whitespace, or force full raw context)\n\n## Installation\n\n```bash\n# Core features only - lightweight, no ML dependencies\npip install tenets\n\n# Add specific features\npip install tenets[light] # Adds keyword extraction & BM25/TF-IDF ranking\npip install tenets[viz] # Adds visualization capabilities\npip install tenets[ml] # Adds deep learning models (2GB+)\npip install tenets[all] # Everything\n```\n\n**Python 3.13 Note:** Compatible but some ML features have limitations. Use Python 3.12 for full ML support.\n\n## Quick Start\n\n### Three Ranking Modes\n\nTenets offers three modes that balance speed vs. accuracy for both `distill` and `rank` commands:\n\n| Mode | Speed | Accuracy | Use Case | What It Does |\n| ------------ | ----------- | -------- | ------------------------ | ------------------------------------------------------------ |\n| **fast** | Fastest | Good | Quick exploration | Keyword & path matching, basic relevance |\n| **balanced** | 1.5x slower | Better | Most use cases (default) | BM25 scoring, keyword extraction, structure analysis |\n| **thorough** | 4x slower | Best | Complex refactoring | ML semantic similarity, pattern detection, dependency graphs |\n\n### Core Commands\n\n#### `distill` - Build Context with Content\n\n```bash\n# Basic usage - finds and aggregates relevant files\ntenets distill \"implement OAuth2\" # Searches current directory by default\n\n# Search specific directory\ntenets distill \"implement OAuth2\" ./src\n\n# Copy to clipboard (great for AI chats)\ntenets distill \"fix payment bug\" --copy\n\n# Generate interactive HTML report\ntenets distill \"analyze auth flow\" --format html -o report.html\n\n# Speed/accuracy trade-offs\ntenets distill \"debug issue\" --mode fast # <5s, keyword matching\ntenets distill \"refactor API\" --mode thorough # Semantic analysis\n\n# Transform content to save tokens\ntenets distill \"review code\" --remove-comments --condense\n```\n\n#### `rank` - Preview Files Without Content\n\n```bash\n# See what files would be included (much faster than distill!)\ntenets rank \"implement payments\" --top 20 # Searches current directory by default\n\n# Understand WHY files are ranked\ntenets rank \"fix auth\" --factors\n\n# Tree view for structure understanding\ntenets rank \"add caching\" --tree --scores\n\n# Export for automation\ntenets rank \"database migration\" --format json | jq '.files[].path'\n\n# Search specific directory\ntenets rank \"payment refactoring\" ./src --top 10\n```\n\n### Sessions & Persistence\n\n```bash\n# Create a working session\ntenets session create payment-feature\n\n# Pin critical files for the session\ntenets instill --session payment-feature --add-file src/core/payment.py\n\n# Add guiding principles (tenets)\ntenets tenet add \"Always validate inputs\" --priority critical\ntenets instill --session payment-feature\n\n# Build context using the session\ntenets distill \"add refund flow\" --session payment-feature\n```\n\n### Other Commands\n\n```bash\n# Visualize architecture\ntenets viz deps --output architecture.svg # Dependency graph\ntenets viz deps --format html -o deps.html # Interactive HTML\n\n# Track development patterns\ntenets chronicle --since \"last week\" # Git activity\ntenets momentum --team # Sprint velocity\n\n# Analyze codebase\ntenets examine . --complexity --threshold 10 # Find complex code\n```\n\n## Configuration\n\nCreate `.tenets.yml` in your project:\n\n```yaml\nranking:\n algorithm: balanced # fast | balanced | thorough\n threshold: 0.1\n use_git: true # Use git signals for relevance\n\ncontext:\n max_tokens: 100000\n\noutput:\n format: markdown\n copy_on_distill: true # Auto-copy to clipboard\n\nignore:\n - vendor/\n - '*.generated.*'\n```\n\n## Documentation\n\n- **[Full Documentation](https://tenets.dev/docs)** - Complete guide and API reference\n- **[CLI Reference](docs/CLI.md)** - All commands and options\n- **[Configuration Guide](docs/CONFIG.md)** - Detailed configuration options\n- **[Architecture Overview](docs/ARCHITECTURE.md)** - How tenets works internally\n\n### Smart Summarization\n\nWhen files exceed token budgets, tenets intelligently preserves:\n\n- Function/class signatures\n- Import statements\n- Complex logic blocks\n- Documentation and comments\n- Recent changes\n\nFor more details on the summarization system, see [Architecture Documentation](docs/ARCHITECTURE.md).\n\n## Advanced Features\n\n### Test File Handling\n\nTests are **excluded by default** for most prompts, **automatically included** when your prompt mentions testing:\n\n```bash\n# Tests excluded (better context):\ntenets distill \"explain auth flow\"\n\n# Tests included (detected by intent):\ntenets distill \"write tests for auth\"\ntenets distill \"fix failing tests\"\n\n# Manual override:\ntenets distill \"review code\" --include-tests\ntenets distill \"fix test_user.py\" --exclude-tests\n```\n\n### Output Formats\n\n```bash\n# Markdown (default, optimized for AI)\ntenets distill \"implement OAuth2\" --format markdown\n\n# Interactive HTML with search, charts, copy buttons\ntenets distill \"review API\" --format html -o report.html\n\n# JSON for programmatic use\ntenets distill \"analyze\" --format json | jq '.files[0]'\n\n# XML optimized for Claude\ntenets distill \"debug issue\" --format xml\n```\n\n## Python API\n\n```python\nfrom tenets import Tenets\n\n# Initialize\ntenets = Tenets()\n\n# Basic usage\nresult = tenets.distill(\"implement user authentication\")\nprint(f\"Generated {result.token_count} tokens\")\n\n# Rank files without content\nfrom tenets.core.ranking import RelevanceRanker\nranker = RelevanceRanker(algorithm=\"balanced\")\nranked_files = ranker.rank(files, prompt_context, threshold=0.1)\n\nfor file in ranked_files[:10]:\n print(f\"{file.path}: {file.relevance_score:.3f}\")\n```\n\n## Supported Languages\n\nSpecialized analyzers for Python, JavaScript/TypeScript, Go, Java, C/C++, Ruby, PHP, Rust, and more. Configuration and documentation files are analyzed with smart heuristics for YAML, TOML, JSON, Markdown, etc.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## Contact\n\nteam@tenets.dev // team@manic.agency\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Context that feeds your prompts",
"version": "0.3.2",
"project_urls": {
"Changelog": "https://github.com/jddunn/tenets/blob/main/CHANGELOG.md",
"Documentation": "https://tenets.dev/docs",
"Homepage": "https://github.com/jddunn/tenets",
"Issues": "https://github.com/jddunn/tenets/issues",
"Repository": "https://github.com/jddunn/tenets"
},
"split_keywords": [
"ai",
" code-analysis",
" code-intelligence",
" context-management",
" developer-tools",
" llm",
" prompt-engineering"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f5120b4bc0bb1b9865ec72c74c2efaff38ad4e75fc16d343f76136b5b29b5e5b",
"md5": "7306969e06adf70e73431e90a9448c05",
"sha256": "3de33c9e9166d16fc3cd5235382dcc5bf30e3368f229c7f3111b2a20eaf6475f"
},
"downloads": -1,
"filename": "tenets-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7306969e06adf70e73431e90a9448c05",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 737436,
"upload_time": "2025-09-13T03:49:28",
"upload_time_iso_8601": "2025-09-13T03:49:28.087911Z",
"url": "https://files.pythonhosted.org/packages/f5/12/0b4bc0bb1b9865ec72c74c2efaff38ad4e75fc16d343f76136b5b29b5e5b/tenets-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5f3d525cd9ad48146896c1eb2406b2e8497e802c9f54b73203ce7a71112c0307",
"md5": "c1d2f923dac217a98bc53532d23646a2",
"sha256": "4d3eb7ef7a7ac19f7ce105b86c748a934d8493c4bf52685ee59a15662ed8656e"
},
"downloads": -1,
"filename": "tenets-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "c1d2f923dac217a98bc53532d23646a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 656890,
"upload_time": "2025-09-13T03:49:30",
"upload_time_iso_8601": "2025-09-13T03:49:30.070390Z",
"url": "https://files.pythonhosted.org/packages/5f/3d/525cd9ad48146896c1eb2406b2e8497e802c9f54b73203ce7a71112c0307/tenets-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 03:49:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jddunn",
"github_project": "tenets",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tenets"
}
JSON
