ctxeng 0.1.0__tar.gz

ctxeng-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install ctxeng + dev deps
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check ctxeng/
+
+      - name: Type check with mypy
+        run: mypy ctxeng/ --ignore-missing-imports
+        continue-on-error: true
+
+      - name: Run tests with coverage
+        run: |
+          pytest tests/ --cov=ctxeng --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          pip install hatchling
+          python -m hatchling build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

ctxeng-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+.pytest_cache/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.env

ctxeng-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to ctxeng
+
+Thank you for helping make ctxeng better! This guide covers everything you need to get started.
+
+## Development setup
+
+```bash
+git clone https://github.com/your-username/python-context-engineer
+cd python-context-engineer
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest                          # run all tests
+pytest tests/unit/              # unit tests only
+pytest -k "test_scoring"        # filter by name
+pytest --cov=ctxeng             # with coverage
+```
+
+## Code style
+
+We use `ruff` for linting:
+
+```bash
+ruff check ctxeng/
+ruff format ctxeng/
+```
+
+## Project layout
+
+```
+ctxeng/
+├── __init__.py         Public API exports
+├── core.py             ContextEngine main class
+├── builder.py          ContextBuilder fluent API
+├── models.py           Data classes (Context, ContextFile, TokenBudget)
+├── scorer.py           File relevance scoring (keyword, AST, git, path)
+├── optimizer.py        Token counting, budget fitting, smart truncation
+├── cli.py              CLI entry point
+├── sources/            File collectors (filesystem, git, explicit)
+└── integrations/       LLM client helpers (Claude, OpenAI, LangChain)
+```
+
+## How to add a new scoring signal
+
+1. Add a function `_my_signal_score(content, query, ...) -> float` in `scorer.py`
+2. Call it from `score_file()` and add it to the weighted average
+3. Add a unit test in `tests/unit/test_core.py`
+4. Document it in the README scoring table
+
+## How to add a new LLM integration
+
+1. Add an `ask_mymodel(ctx, ...) -> str` function in `ctxeng/integrations/__init__.py`
+2. Follow the pattern of `ask_claude` / `ask_openai`
+3. Add it to `pyproject.toml` optional-dependencies
+4. Document it in the README
+
+## Submitting a PR
+
+1. Fork the repo and create a branch: `git checkout -b feat/my-feature`
+2. Write code + tests
+3. Run `pytest` and `ruff check` — both must pass
+4. Open a PR with a clear description of what it does and why
+
+## Reporting bugs
+
+Open an issue with:
+- Python version
+- `ctxeng` version
+- Minimal reproduction case
+- Expected vs actual behavior

ctxeng-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ctxeng contributors
+
+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.

ctxeng-0.1.0/PKG-INFO

@@ -0,0 +1,412 @@
+Metadata-Version: 2.4
+Name: ctxeng
+Version: 0.1.0
+Summary: Build perfect LLM context from your Python codebase — automatically.
+Project-URL: Homepage, https://github.com/sayeem3051/python-context-engineer
+Project-URL: Repository, https://github.com/sayeem3051/python-context-engineer
+Project-URL: Issues, https://github.com/sayeem3051/python-context-engineer/issues
+Project-URL: Changelog, https://github.com/sayeem3051/python-context-engineer/blob/main/CHANGELOG.md
+Author: ctxeng contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,codebase,context,context-engineering,developer-tools,gpt,llm,openai,token
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: anthropic>=0.25; extra == 'all'
+Requires-Dist: langchain-core>=0.2; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: tiktoken>=0.7; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: tiktoken>=0.7; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.7; extra == 'tiktoken'
+Description-Content-Type: text/markdown
+
+# ctxeng — Python Context Engineering Library
+
+<p align="center">
+  <strong>Stop copy-pasting files into ChatGPT.<br>
+  Build the perfect LLM context from your codebase, automatically.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/ctxeng/"><img src="https://img.shields.io/pypi/v/ctxeng?color=blue&label=pypi" alt="PyPI"></a>
+  <a href="https://github.com/sayeem3051/python-context-engineer/actions"><img src="https://github.com/sayeem3051/python-context-engineer/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/ctxeng/"><img src="https://img.shields.io/pypi/pyversions/ctxeng" alt="Python"></a>
+  <img src="https://img.shields.io/github/license/sayeem3051/python-context-engineer" alt="License">
+  <img src="https://img.shields.io/pypi/dm/ctxeng?label=downloads" alt="Downloads">
+</p>
+
+---
+
+**Context engineering** is the new prompt engineering.
+The quality of your LLM's output depends almost entirely on *what you put in the context window* — not how you phrase the question.
+
+`ctxeng` solves this automatically:
+
+- **Scans your codebase** and scores every file for relevance to your query
+- **Ranks by signal** — keyword overlap, AST symbols, git recency, import graph
+- **Fits the budget** — smart truncation keeps the best parts within any model's token limit
+- **Ships ready to paste** — XML, Markdown, or plain text output that works with Claude, GPT-4o, Gemini, and every other model
+
+Zero required dependencies. Works with any LLM.
+
+---
+
+## Installation
+
+```bash
+pip install ctxeng
+```
+
+For accurate token counting (strongly recommended):
+
+```bash
+pip install "ctxeng[tiktoken]"
+```
+
+For one-line LLM calls:
+
+```bash
+pip install "ctxeng[anthropic]"    # Claude
+pip install "ctxeng[openai]"       # GPT-4o
+pip install "ctxeng[all]"          # everything
+```
+
+---
+
+## Quickstart
+
+### Python API
+
+```python
+from ctxeng import ContextEngine
+
+engine = ContextEngine(root=".", model="claude-sonnet-4")
+ctx = engine.build("Fix the authentication bug in the login flow")
+
+print(ctx.summary())
+# Context summary (12,340 tokens / 197,440 budget):
+#   Included : 8 files
+#   Skipped  : 23 files (over budget)
+#   [████████  ] 0.84  src/auth/login.py
+#   [███████   ] 0.71  src/auth/middleware.py
+#   [█████     ] 0.53  src/models/user.py
+#   [████      ] 0.41  tests/test_auth.py
+#   ...
+
+# Paste directly into your LLM
+print(ctx.to_string())
+```
+
+### Fluent Builder API
+
+```python
+from ctxeng import ContextBuilder
+
+ctx = (
+    ContextBuilder(root=".")
+    .for_model("gpt-4o")
+    .only("**/*.py")
+    .exclude("tests/**", "migrations/**")
+    .from_git_diff()                        # only changed files
+    .with_system("You are a senior Python engineer. Be concise.")
+    .build("Refactor the payment module to use async/await")
+)
+
+print(ctx.to_string("markdown"))
+```
+
+### One-line LLM call
+
+```python
+from ctxeng import ContextEngine
+from ctxeng.integrations import ask_claude
+
+engine = ContextEngine(".", model="claude-sonnet-4")
+ctx = engine.build("Why is the test_login test failing?")
+
+response = ask_claude(ctx)
+print(response)
+```
+
+### CLI
+
+```bash
+# Build context for a query and print to stdout
+ctxeng build "Fix the auth bug"
+
+# Focused on git-changed files only
+ctxeng build "Review my changes" --git-diff
+
+# Target a specific model with markdown output
+ctxeng build "Refactor this" --model gpt-4o --fmt markdown
+
+# Save to file
+ctxeng build "Explain the payment flow" --output context.md
+
+# Project stats
+ctxeng info
+```
+
+---
+
+## How It Works
+
+```
+Your codebase                    ctxeng                      Your LLM
+─────────────                ────────────────            ────────────────
+src/auth/login.py  ─┐
+src/models/user.py ─┤  1. Score files         2. Fit budget     <context>
+src/api/routes.py  ─┼─► vs query + git  ─►   smart truncate ─► <file>...</file>
+tests/test_auth.py ─┤     recency + AST        token-aware       <file>...</file>
+...500 more files  ─┘                                           </context>
+```
+
+### Scoring signals
+
+Each file gets a relevance score from 0 → 1, combining:
+
+| Signal | What it measures |
+|--------|-----------------|
+| **Keyword overlap** | How many query terms appear in the file content |
+| **AST symbols** | Class/function/import names that match the query (Python) |
+| **Path relevance** | Filename and directory names matching query tokens |
+| **Git recency** | Files touched in recent commits score higher |
+
+### Token budget optimization
+
+Files are ranked by score and filled greedily into the token budget. Files that don't fit are **smart-truncated** (head + tail, never middle) rather than dropped entirely — the top of a file has imports and class defs; the tail has recent changes. Both are high-signal.
+
+---
+
+## Examples
+
+### Debug a failing test
+
+```python
+from ctxeng import ContextBuilder
+from ctxeng.integrations import ask_claude
+
+ctx = (
+    ContextBuilder(".")
+    .for_model("claude-sonnet-4")
+    .include_files("tests/test_payment.py", "src/payment/service.py")
+    .with_system("You are a Python debugging expert.")
+    .build("test_charge_user is failing with a KeyError on 'amount'")
+)
+response = ask_claude(ctx)
+```
+
+### Code review on a PR
+
+```python
+# Only include what changed in this branch vs main
+ctx = (
+    ContextBuilder(".")
+    .for_model("gpt-4o")
+    .from_git_diff(base="main")
+    .with_system("Do a thorough code review. Flag security issues first.")
+    .build("Review this pull request")
+)
+```
+
+### Explain an unfamiliar codebase
+
+```python
+from ctxeng import ContextEngine
+
+engine = ContextEngine(
+    root="/path/to/project",
+    model="gemini-1.5-pro",  # 1M token window → include everything
+)
+ctx = engine.build("Give me a high-level architecture overview")
+print(ctx.to_string())
+```
+
+### Targeted refactor
+
+```python
+ctx = (
+    ContextBuilder(".")
+    .for_model("claude-sonnet-4")
+    .only("src/database/**/*.py")
+    .exclude("**/*_test.py")
+    .build("Convert all raw SQL queries to use SQLAlchemy ORM")
+)
+```
+
+---
+
+## API Reference
+
+### `ContextEngine`
+
+```python
+ContextEngine(
+    root=".",               # Project root
+    model="claude-sonnet-4",# Sets token budget automatically
+    budget=None,            # Or explicit TokenBudget(total=50_000)
+    max_file_size_kb=500,   # Skip files larger than this
+    include_patterns=None,  # ["**/*.py"] — only these files
+    exclude_patterns=None,  # ["tests/**"] — skip these
+    use_git=True,           # Use git recency signal
+)
+```
+
+```python
+engine.build(
+    query="",               # What you want the LLM to do
+    files=None,             # Explicit list of paths (skips auto-discovery)
+    git_diff=False,         # Only changed files
+    git_base="HEAD",        # Diff base ref
+    system_prompt="",       # System prompt (counts against budget)
+    fmt="xml",              # "xml" | "markdown" | "plain"
+)
+# → Context
+```
+
+### `ContextBuilder` (fluent API)
+
+```python
+ContextBuilder(root=".")
+    .for_model("gpt-4o")
+    .with_budget(total=50_000, reserved_output=4096)
+    .only("**/*.py", "**/*.yaml")
+    .exclude("tests/**", "migrations/**")
+    .include_files("src/specific.py")
+    .from_git_diff(base="main")
+    .with_system("You are an expert Python engineer.")
+    .max_file_size(200)     # KB
+    .no_git()
+    .build("query")
+# → Context
+```
+
+### `Context`
+
+```python
+ctx.to_string(fmt="xml")    # → str ready to paste into an LLM
+ctx.summary()               # → human-readable summary with token counts
+ctx.files                   # → list[ContextFile], sorted by relevance
+ctx.skipped_files           # → files that didn't fit the budget
+ctx.total_tokens            # → estimated token usage
+ctx.budget.available        # → remaining token budget
+```
+
+### `TokenBudget`
+
+```python
+TokenBudget.for_model("claude-sonnet-4")  # auto-detect limit
+TokenBudget(total=50_000, reserved_output=2048, reserved_system=512)
+```
+
+Supported models (auto-detected): `claude-opus-4`, `claude-sonnet-4`, `claude-haiku-4`, `gpt-4o`, `gpt-4-turbo`, `gpt-4`, `gpt-3.5-turbo`, `gemini-1.5-pro`, `gemini-1.5-flash`, `llama-3`.
+
+---
+
+## CLI Reference
+
+```
+ctxeng [--root PATH] <command> [options]
+
+Commands:
+  build   Build context for a query
+  info    Show project info and file stats
+
+build options:
+  --model, -m     Target model (default: claude-sonnet-4)
+  --fmt, -f       Output format: xml | markdown | plain (default: xml)
+  --output, -o    Write to file instead of stdout
+  --only          Glob patterns to include
+  --exclude       Glob patterns to exclude
+  --files         Explicit file list
+  --git-diff      Only include git-changed files
+  --git-base      Git base ref (default: HEAD)
+  --system        System prompt text
+  --budget        Override total token budget
+  --no-git        Disable git recency scoring
+  --max-size      Max file size in KB (default: 500)
+```
+
+---
+
+## Supported Models
+
+| Model | Context window | Auto-detected |
+|-------|---------------|---------------|
+| claude-opus-4, claude-sonnet-4, claude-haiku-4 | 200K | ✓ |
+| gpt-4o, gpt-4-turbo | 128K | ✓ |
+| gpt-4 | 8K | ✓ |
+| gpt-3.5-turbo | 16K | ✓ |
+| gemini-1.5-pro, gemini-1.5-flash | 1M | ✓ |
+| llama-3 | 32K | ✓ |
+| any other | 32K (safe default) | — |
+
+---
+
+## Why not just paste files manually?
+
+You could. But you'll hit these problems immediately:
+
+- **Token limit errors** — too many files, context overflows
+- **Irrelevant noise** — wrong files dilute signal, hurt output quality
+- **Stale context** — you forget to update when code changes
+- **Manual effort** — figuring out which files matter takes time
+
+`ctxeng` solves all four. The right files, in the right order, trimmed to fit, every time.
+
+---
+
+## Roadmap
+
+- [ ] Semantic similarity scoring (optional embedding model)
+- [ ] `ctxeng watch` — auto-rebuild context on file changes
+- [ ] VSCode extension
+- [ ] Import graph analysis (include files imported by relevant files)
+- [ ] `.ctxengignore` file support
+- [ ] Streaming context into LLM APIs
+
+---
+
+## Contributing
+
+PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+git clone https://github.com/sayeem3051/python-context-engineer
+cd python-context-engineer
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## License
+
+MIT. Use freely, modify as needed, contribute back if you can.
+
+---
+
+<p align="center">
+  If <code>ctxeng</code> saved you time, please ⭐ the repo — it helps others find it.
+</p>