{"id":48083621,"url":"https://github.com/sayeem3051/python-context-engineer","last_synced_at":"2026-04-10T22:00:40.622Z","repository":{"id":349157120,"uuid":"1201252238","full_name":"Sayeem3051/python-context-engineer","owner":"Sayeem3051","description":"Build perfect LLM context from your Python codebase — automatically","archived":false,"fork":false,"pushed_at":"2026-04-08T16:51:53.000Z","size":473,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-08T20:43:15.428Z","etag":null,"topics":["artificial-intelligence","claude","codebase","context-engineering","developer-tools","gpt","llm","machine-learning","openai","prompt-engineering","python","token-optimization"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/ctxeng/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sayeem3051.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T12:24:40.000Z","updated_at":"2026-04-08T16:47:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Sayeem3051/python-context-engineer","commit_stats":null,"previous_names":["sayeem3051/python-context-engineer"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Sayeem3051/python-context-engineer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sayeem3051%2Fpython-context-engineer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sayeem3051%2Fpython-context-engineer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sayeem3051%2Fpython-context-engineer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sayeem3051%2Fpython-context-engineer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sayeem3051","download_url":"https://codeload.github.com/Sayeem3051/python-context-engineer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sayeem3051%2Fpython-context-engineer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31660628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"ssl_error","status_checked_at":"2026-04-10T17:19:13.364Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","claude","codebase","context-engineering","developer-tools","gpt","llm","machine-learning","openai","prompt-engineering","python","token-optimization"],"created_at":"2026-04-04T15:01:45.180Z","updated_at":"2026-04-10T22:00:40.612Z","avatar_url":"https://github.com/Sayeem3051.png","language":"Python","readme":"# ctxeng — Python Context Engineering Library\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStop copy-pasting files into ChatGPT.\u003cbr\u003e\n  Build the perfect LLM context from your codebase, automatically.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/ctxeng/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/ctxeng?color=blue\u0026label=pypi\u0026cacheSeconds=3600\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/sayeem3051/python-context-engineer/actions\"\u003e\u003cimg src=\"https://github.com/sayeem3051/python-context-engineer/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/ctxeng/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/ctxeng?cacheSeconds=3600\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/sayeem3051/python-context-engineer?cacheSeconds=3600\" alt=\"License\"\u003e\n  \u003ca href=\"https://pepy.tech/project/ctxeng\"\u003e\u003cimg src=\"https://static.pepy.tech/badge/ctxeng/month\" alt=\"Downloads\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/ctxeng-demo.gif\" alt=\"ctxeng demo\" width=\"800\"\u003e\n\u003c/p\u003e\n\n---\n\n**Context engineering** is the new prompt engineering.\nThe quality of your LLM's output depends almost entirely on *what you put in the context window* — not how you phrase the question.\n\n`ctxeng` solves this automatically:\n\n- **Scans your codebase** and scores every file for relevance to your query\n- **Ranks by signal** — keyword overlap, AST symbols, git recency, import graph\n- **Fits the budget** — smart truncation keeps the best parts within any model's token limit\n- **Ships ready to paste** — XML, Markdown, or plain text output that works with Claude, GPT-4o, Gemini, and every other model\n\nOne small dependency ([pathspec](https://pypi.org/project/pathspec/)) powers ``.ctxengignore`` (gitignore-style patterns). Works with any LLM.\n\n---\n\n## Installation\n\n```bash\n# Core install (includes .ctxengignore support)\npip install ctxeng\n# pathspec is included automatically\n```\n\nFor accurate token counting (strongly recommended):\n\n```bash\npip install \"ctxeng[tiktoken]\"\n```\n\nFor file watching (used by `ctxeng watch` when that command is available):\n\n```bash\npip install \"ctxeng[watch]\"\n```\n\nFor semantic similarity scoring (optional local embeddings):\n\n```bash\npip install \"ctxeng[semantic]\"\n```\n\nFor one-line LLM calls:\n\n```bash\npip install \"ctxeng[anthropic]\"    # Claude\npip install \"ctxeng[openai]\"       # GPT-4o\npip install \"ctxeng[all]\"          # everything\n```\n\n---\n\n## Quickstart\n\n### Python API\n\n```python\nfrom ctxeng import ContextEngine\n\nengine = ContextEngine(root=\".\", model=\"claude-sonnet-4\")\nctx = engine.build(\"Fix the authentication bug in the login flow\")\n\nprint(ctx.summary())\n# Context summary (12,340 tokens / 197,440 budget):\n#   Included : 8 files\n#   Skipped  : 23 files (over budget)\n#   Est. cost: ~$0.037 (claude-sonnet-4)\n#   [████████  ] 0.84  src/auth/login.py\n#   [███████   ] 0.71  src/auth/middleware.py\n#   [█████     ] 0.53  src/models/user.py\n#   [████      ] 0.41  tests/test_auth.py\n#   ...\n\n# Paste directly into your LLM\nprint(ctx.to_string())\n```\n\n### Fluent Builder API\n\n```python\nfrom ctxeng import ContextBuilder\n\nctx = (\n    ContextBuilder(root=\".\")\n    .for_model(\"gpt-4o\")\n    .only(\"**/*.py\")\n    .exclude(\"tests/**\", \"migrations/**\")\n    .from_git_diff()                        # only changed files\n    .with_system(\"You are a senior Python engineer. Be concise.\")\n    .build(\"Refactor the payment module to use async/await\")\n)\n\nprint(ctx.to_string(\"markdown\"))\n```\n\n### One-line LLM call\n\n```python\nfrom ctxeng import ContextEngine\nfrom ctxeng.integrations import ask_claude\n\nengine = ContextEngine(\".\", model=\"claude-sonnet-4\")\nctx = engine.build(\"Why is the test_login test failing?\")\n\nresponse = ask_claude(ctx)\nprint(response)\n```\n\n### CLI\n\n```bash\n# Build context for a query and print to stdout\nctxeng build \"Fix the auth bug\"\n\n# Focused on git-changed files only\nctxeng build \"Review my changes\" --git-diff\n\n# Target a specific model with markdown output\nctxeng build \"Refactor this\" --model gpt-4o --fmt markdown\n\n# Save to file\nctxeng build \"Explain the payment flow\" --output context.md\n\n# Project stats\nctxeng info\n```\n\n### Watch mode\n\nAutomatically rebuild context when files change (requires `watchdog`):\n\n```bash\npip install \"ctxeng[watch]\"\nctxeng watch \"Fix the auth bug\" --output context.md\n```\n\nExample output:\n\n```text\n[14:32:01] File changed: src/auth/login.py\n[14:32:01] Rebuilding context...\n[14:32:01] Done. 8 files, 12,340 tokens, ~$0.037\n[14:32:01] Written to: context.md\n```\n\n### `.ctxengignore`\n\nAdd a **`.ctxengignore`** file at your project root to exclude paths from filesystem discovery (same syntax as **`.gitignore`**). It is applied automatically when you run `ctxeng build`, `ctxeng info`, or `ContextEngine` / `ContextBuilder` without explicit `--files` / `include_files`.\n\nExample `.ctxengignore`:\n\n```gitignore\n# Dependencies\nnode_modules/\nvenv/\n.venv/\n\n# Build artifacts\ndist/\nbuild/\n*.egg-info/\n\n# Migrations\nmigrations/**\n**/migrations/**\n\n# Lock files\n*.lock\npoetry.lock\npackage-lock.json\n```\n\nSupported patterns include `*`, `?`, `**`, directory slashes, and negation with `!` (full gitwildmatch semantics via pathspec). If `.ctxengignore` is missing, nothing is excluded beyond ctxeng’s built-in skips.\n\n```python\nfrom pathlib import Path\nfrom ctxeng import parse_ctxengignore\n\npatterns = parse_ctxengignore(Path(\".\"))\n# → list of pattern strings, or [] if no file\n```\n\n### Import graph (Python)\n\nAfter files are scored, **ctxeng** parses static ``import`` / ``from … import`` statements in each discovered ``.py`` file, resolves **relative imports** from the file’s location, and can **pull in imported modules** from the same collection set before the token budget is applied.\n\n- **Default:** one hop (`import_graph_depth=1`), relevance for added files = parent score × **0.7**\n- **Edges only** to files already in the current discovery set (filesystem / git / explicit list)\n- Stdlib and third-party imports are ignored (no file under your root → no edge)\n\n```python\nfrom ctxeng import ContextEngine, ContextBuilder\n\n# Engine: on by default; adjust depth or turn off\nengine = ContextEngine(\n    root=\".\",\n    use_import_graph=True,\n    import_graph_depth=2,\n)\n\nctx = (\n    ContextBuilder(\".\")\n    .for_model(\"claude-sonnet-4\")\n    .use_import_graph(depth=2)   # follow two hops of local imports\n    # .no_import_graph()         # disable expansion\n    .build(\"Fix the checkout bug in orders\")\n)\n```\n\nCLI (import expansion is **on** by default):\n\n```bash\nctxeng build \"Refactor auth\" --no-import-graph\nctxeng build \"Refactor auth\" --import-graph-depth 2\n```\n\nLower-level API:\n\n```python\nfrom pathlib import Path\nfrom ctxeng import build_import_graph, expand_with_imports\nfrom ctxeng.models import ContextFile\n\npaths = [Path(\"src/app.py\"), Path(\"src/lib.py\")]\ngraph = build_import_graph(Path(\".\"), paths)\n# graph[path] → list of imported paths (within `paths`)\n\nexpanded = expand_with_imports(\n    [ContextFile(path=paths[0], content=\"...\", relevance_score=0.9, language=\"python\")],\n    graph,\n    Path(\".\"),\n    max_depth=1,\n    score_decay=0.7,\n)\n```\n\n### Cost estimates\n\n`ContextEngine` fills ``ctx.cost_estimate`` with a **rough USD** figure for **input tokens** only, using built-in per‑1K rates for common models (see ``ctxeng.costs.COST_PER_1K_INPUT_TOKENS``). Unknown model names yield ``None``. Rates are indicative—verify with your provider before budgeting.\n\n``Context.summary()`` includes a line when a cost is known:\n\n```text\nContext summary (12,340 tokens / 197,440 budget):\n  Included : 8 files\n  Skipped  : 23 files (over budget)\n  Est. cost: ~$0.037 (claude-sonnet-4)\n```\n\n```python\nfrom ctxeng import estimate_cost, ContextEngine\n\nengine = ContextEngine(root=\".\", model=\"gpt-4o\")\nctx = engine.build(\"Explain this module\")\nprint(ctx.cost_estimate)   # float | None\nprint(ctx.summary())       # includes Est. cost when known\n```\n\nCLI: cost line is **on** by default; use ``--no-show-cost`` to omit it from stderr.\n\n---\n\n## How It Works\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/ctxeng_flowchart.svg\" alt=\"ctxeng flow: your codebase → score files (query, git, AST, imports) → fit token budget → LLM-ready context\" width=\"680\" style=\"max-width: 100%; height: auto;\"\u003e\n\u003c/p\u003e\n\n### Scoring signals\n\nEach file gets a relevance score from 0 → 1, combining:\n\n| Signal | What it measures |\n|--------|-----------------|\n| **Keyword overlap** | How many query terms appear in the file content |\n| **AST symbols** | Class/function/import names that match the query (Python) |\n| **Path relevance** | Filename and directory names matching query tokens |\n| **Git recency** | Files touched in recent commits score higher |\n| **Import expansion** | After scoring, locally imported Python modules can be added with a decayed score |\n| **Semantic similarity** | Optional embedding similarity between query and file content |\n\n### Token budget optimization\n\nFiles 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.\n\n---\n\n## Examples\n\n### Debug a failing test\n\n```python\nfrom ctxeng import ContextBuilder\nfrom ctxeng.integrations import ask_claude\n\nctx = (\n    ContextBuilder(\".\")\n    .for_model(\"claude-sonnet-4\")\n    .include_files(\"tests/test_payment.py\", \"src/payment/service.py\")\n    .with_system(\"You are a Python debugging expert.\")\n    .build(\"test_charge_user is failing with a KeyError on 'amount'\")\n)\nresponse = ask_claude(ctx)\n```\n\n### Code review on a PR\n\n```python\n# Only include what changed in this branch vs main\nctx = (\n    ContextBuilder(\".\")\n    .for_model(\"gpt-4o\")\n    .from_git_diff(base=\"main\")\n    .with_system(\"Do a thorough code review. Flag security issues first.\")\n    .build(\"Review this pull request\")\n)\n```\n\n### Explain an unfamiliar codebase\n\n```python\nfrom ctxeng import ContextEngine\n\nengine = ContextEngine(\n    root=\"/path/to/project\",\n    model=\"gemini-1.5-pro\",  # 1M token window → include everything\n)\nctx = engine.build(\"Give me a high-level architecture overview\")\nprint(ctx.to_string())\n```\n\n### Targeted refactor\n\n```python\nctx = (\n    ContextBuilder(\".\")\n    .for_model(\"claude-sonnet-4\")\n    .only(\"src/database/**/*.py\")\n    .exclude(\"**/*_test.py\")\n    .build(\"Convert all raw SQL queries to use SQLAlchemy ORM\")\n)\n```\n\n---\n\n## API Reference\n\n### `ContextEngine`\n\n```python\nContextEngine(\n    root=\".\",               # Project root\n    model=\"claude-sonnet-4\",# Sets token budget automatically\n    budget=None,            # Or explicit TokenBudget(total=50_000)\n    max_file_size_kb=500,   # Skip files larger than this\n    include_patterns=None,  # [\"**/*.py\"] — only these files\n    exclude_patterns=None,  # [\"tests/**\"] — skip these\n    use_git=True,           # Use git recency signal\n    use_import_graph=True,  # Add local Python imports of scored files\n    import_graph_depth=1,    # Hops along the import graph\n)\n```\n\n```python\nengine.build(\n    query=\"\",               # What you want the LLM to do\n    files=None,             # Explicit list of paths (skips auto-discovery)\n    git_diff=False,         # Only changed files\n    git_base=\"HEAD\",        # Diff base ref\n    system_prompt=\"\",       # System prompt (counts against budget)\n    fmt=\"xml\",              # \"xml\" | \"markdown\" | \"plain\"\n)\n# → Context\n```\n\n### `ContextBuilder` (fluent API)\n\n```python\nContextBuilder(root=\".\")\n    .for_model(\"gpt-4o\")\n    .with_budget(total=50_000, reserved_output=4096)\n    .only(\"**/*.py\", \"**/*.yaml\")\n    .exclude(\"tests/**\", \"migrations/**\")\n    .include_files(\"src/specific.py\")\n    .from_git_diff(base=\"main\")\n    .with_system(\"You are an expert Python engineer.\")\n    .max_file_size(200)     # KB\n    .no_git()\n    .use_import_graph(depth=2)  # optional; omit for default depth 1\n    .build(\"query\")\n# → Context\n```\n\n### `Context`\n\n```python\nctx.to_string(fmt=\"xml\")    # → str ready to paste into an LLM\nctx.summary(show_cost=True) # → summary; optional show_cost=False hides Est. cost\nctx.cost_estimate           # → float | None (rough input USD for known models)\nctx.files                   # → list[ContextFile], sorted by relevance\nctx.skipped_files           # → files that didn't fit the budget\nctx.total_tokens            # → estimated token usage\nctx.budget.available        # → remaining token budget\n```\n\n### `TokenBudget`\n\n```python\nTokenBudget.for_model(\"claude-sonnet-4\")  # auto-detect limit\nTokenBudget(total=50_000, reserved_output=2048, reserved_system=512)\n```\n\nSupported 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`.\n\n---\n\n## CLI Reference\n\n```\nctxeng [--root PATH] \u003ccommand\u003e [options]\n\nCommands:\n  build   Build context for a query\n  info    Show project info and file stats\n\nbuild options:\n  --model, -m     Target model (default: claude-sonnet-4)\n  --fmt, -f       Output format: xml | markdown | plain (default: xml)\n  --output, -o    Write to file instead of stdout\n  --only          Glob patterns to include\n  --exclude       Glob patterns to exclude\n  --files         Explicit file list\n  --git-diff      Only include git-changed files\n  --git-base      Git base ref (default: HEAD)\n  --system        System prompt text\n  --budget        Override total token budget\n  --no-git        Disable git recency scoring\n  --max-size      Max file size in KB (default: 500)\n  --import-graph / --no-import-graph\n                  Expand with local Python import graph (default: on)\n  --import-graph-depth N\n                  Import hops when import graph is on (default: 1)\n  --show-cost / --no-show-cost\n                  Include estimated input cost in stderr summary (default: on)\n  --semantic       Enable semantic similarity scoring (requires sentence-transformers)\n  --semantic-model Semantic model name (default: all-MiniLM-L6-v2)\n\nwatch options:\n  --interval S    Polling interval in seconds (default: 1.0)\n  --semantic       Enable semantic similarity scoring (requires sentence-transformers)\n  --semantic-model Semantic model name (default: all-MiniLM-L6-v2)\n```\n\n---\n\n## Supported Models\n\n| Model | Context window | Auto-detected |\n|-------|---------------|---------------|\n| claude-opus-4, claude-sonnet-4, claude-haiku-4 | 200K | ✓ |\n| gpt-4o, gpt-4-turbo | 128K | ✓ |\n| gpt-4 | 8K | ✓ |\n| gpt-3.5-turbo | 16K | ✓ |\n| gemini-1.5-pro, gemini-1.5-flash | 1M | ✓ |\n| llama-3 | 32K | ✓ |\n| any other | 32K (safe default) | — |\n\n---\n\n## Why not just paste files manually?\n\nYou could. But you'll hit these problems immediately:\n\n- **Token limit errors** — too many files, context overflows\n- **Irrelevant noise** — wrong files dilute signal, hurt output quality\n- **Stale context** — you forget to update when code changes\n- **Manual effort** — figuring out which files matter takes time\n\n`ctxeng` solves all four. The right files, in the right order, trimmed to fit, every time.\n\n---\n\n## Roadmap\n\n- [x] Semantic similarity scoring ✅\n- [x] `ctxeng watch` — auto-rebuild on file changes ✅\n- [x] VSCode extension ✅\n- [x] Streaming context into LLM APIs ✅\n- [x] Cost estimates (input-token USD hint in summary) ✅\n- [x] Import graph analysis (local Python static imports) ✅\n- [x] `.ctxengignore` file support ✅\n\n---\n\n## Contributing\n\nPRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n```bash\ngit clone https://github.com/sayeem3051/python-context-engineer\ncd python-context-engineer\npip install -e \".[dev]\"\npytest\n```\n\n---\n\n## License\n\nMIT. Use freely, modify as needed, contribute back if you can.\n\n---\n\n\u003cp align=\"center\"\u003e\n  If \u003ccode\u003ectxeng\u003c/code\u003e saved you time, please ⭐ the repo — it helps others find it.\n\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsayeem3051%2Fpython-context-engineer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsayeem3051%2Fpython-context-engineer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsayeem3051%2Fpython-context-engineer/lists"}