ctxeng 0.1.0__py3-none-any.whl

ctxeng/__init__.py

@@ -0,0 +1,11 @@
+"""
+ctxeng — Python Context Engineering Library
+Automatically build, compress, and inject perfect LLM context from your codebase.
+"""
+
+from ctxeng.builder import ContextBuilder
+from ctxeng.core import ContextEngine
+from ctxeng.models import Context, ContextFile, TokenBudget
+
+__version__ = "0.1.0"
+__all__ = ["ContextEngine", "ContextBuilder", "Context", "ContextFile", "TokenBudget"]

ctxeng/builder.py

@@ -0,0 +1,115 @@
+"""Fluent builder API for constructing context step by step."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ctxeng.core import ContextEngine
+from ctxeng.models import Context, TokenBudget
+
+
+class ContextBuilder:
+    """
+    Fluent, chainable API for building context.
+
+    Example::
+
+        from ctxeng import ContextBuilder
+
+        ctx = (
+            ContextBuilder(root=".")
+            .for_model("gpt-4o")
+            .only("**/*.py")
+            .exclude("tests/**")
+            .from_git_diff()
+            .with_system("You are a senior Python engineer.")
+            .build("Refactor the payment module to use async/await")
+        )
+        print(ctx.to_string("markdown"))
+    """
+
+    def __init__(self, root: str | Path = ".") -> None:
+        self._root = Path(root).resolve()
+        self._model = "claude-sonnet-4"
+        self._budget: TokenBudget | None = None
+        self._include: list[str] = []
+        self._exclude: list[str] = []
+        self._explicit_files: list[Path] = []
+        self._use_git_diff = False
+        self._git_base = "HEAD"
+        self._system = ""
+        self._max_file_size_kb = 500
+        self._use_git = True
+
+    def for_model(self, model: str) -> ContextBuilder:
+        """Set the target model (determines token budget)."""
+        self._model = model
+        return self
+
+    def with_budget(self, total: int, reserved_output: int = 2048) -> ContextBuilder:
+        """Set an explicit token budget."""
+        self._budget = TokenBudget(total=total, reserved_output=reserved_output)
+        return self
+
+    def only(self, *patterns: str) -> ContextBuilder:
+        """Only include files matching these glob patterns."""
+        self._include.extend(patterns)
+        return self
+
+    def exclude(self, *patterns: str) -> ContextBuilder:
+        """Exclude files matching these glob patterns."""
+        self._exclude.extend(patterns)
+        return self
+
+    def include_files(self, *paths: str | Path) -> ContextBuilder:
+        """Explicitly include specific files (bypasses auto-discovery)."""
+        self._explicit_files.extend(Path(p) for p in paths)
+        return self
+
+    def from_git_diff(self, base: str = "HEAD") -> ContextBuilder:
+        """Only include files changed since `base`."""
+        self._use_git_diff = True
+        self._git_base = base
+        return self
+
+    def with_system(self, prompt: str) -> ContextBuilder:
+        """Set a system prompt (counts against token budget)."""
+        self._system = prompt
+        return self
+
+    def max_file_size(self, kb: int) -> ContextBuilder:
+        """Skip files larger than this size in KB."""
+        self._max_file_size_kb = kb
+        return self
+
+    def no_git(self) -> ContextBuilder:
+        """Disable git-based recency scoring."""
+        self._use_git = False
+        return self
+
+    def build(self, query: str = "") -> Context:
+        """
+        Build and return the optimized Context.
+
+        Args:
+            query: What you want the LLM to do. Be specific for best results.
+
+        Returns:
+            :class:`~ctxeng.models.Context`
+        """
+        engine = ContextEngine(
+            root=self._root,
+            model=self._model,
+            budget=self._budget,
+            max_file_size_kb=self._max_file_size_kb,
+            include_patterns=self._include or None,
+            exclude_patterns=self._exclude or None,
+            use_git=self._use_git,
+        )
+        return engine.build(
+            query=query,
+            files=self._explicit_files or None,
+            git_diff=self._use_git_diff,
+            git_base=self._git_base,
+            system_prompt=self._system,
+        )

ctxeng/cli.py

@@ -0,0 +1,152 @@
+"""
+ctxeng CLI — build and inspect context from the command line.
+
+Usage:
+    ctxeng build "Fix the auth bug"
+    ctxeng build "Refactor payment module" --model gpt-4o --fmt markdown
+    ctxeng build "Review my changes" --git-diff
+    ctxeng build "Explain this file" --files src/core.py src/models.py
+    ctxeng info
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def cmd_build(args: argparse.Namespace) -> None:
+    from ctxeng import ContextBuilder
+
+    builder = (
+        ContextBuilder(root=args.root)
+        .for_model(args.model)
+        .max_file_size(args.max_size)
+    )
+
+    if args.only:
+        builder = builder.only(*args.only)
+    if args.exclude:
+        builder = builder.exclude(*args.exclude)
+    if args.files:
+        builder = builder.include_files(*args.files)
+    if args.git_diff:
+        builder = builder.from_git_diff(args.git_base)
+    if args.system:
+        builder = builder.with_system(args.system)
+    if args.no_git:
+        builder = builder.no_git()
+    if args.budget:
+        builder = builder.with_budget(args.budget)
+
+    query = " ".join(args.query) if args.query else ""
+
+    print(f"Building context for: {query!r}", file=sys.stderr)
+    print(f"Root: {Path(args.root).resolve()}", file=sys.stderr)
+    print(f"Model: {args.model}", file=sys.stderr)
+    print("", file=sys.stderr)
+
+    ctx = builder.build(query)
+
+    print(ctx.summary(), file=sys.stderr)
+    print("", file=sys.stderr)
+    print("─" * 60, file=sys.stderr)
+    print("Context output:", file=sys.stderr)
+    print("─" * 60, file=sys.stderr)
+
+    if args.output:
+        out_path = Path(args.output)
+        out_path.write_text(ctx.to_string(args.fmt), encoding="utf-8")
+        print(f"Written to: {out_path}", file=sys.stderr)
+    else:
+        print(ctx.to_string(args.fmt))
+
+
+def cmd_info(args: argparse.Namespace) -> None:
+    import subprocess
+
+    from ctxeng.optimizer import count_tokens, detect_language
+    from ctxeng.sources import collect_filesystem
+
+    root = Path(args.root).resolve()
+    print(f"Project: {root}")
+
+    # Git info
+    try:
+        r = subprocess.run(["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                           cwd=root, capture_output=True, text=True, timeout=2)
+        if r.returncode == 0:
+            print(f"Branch:  {r.stdout.strip()}")
+        r2 = subprocess.run(["git", "log", "-1", "--format=%h %s"],
+                             cwd=root, capture_output=True, text=True, timeout=2)
+        if r2.returncode == 0:
+            print(f"Commit:  {r2.stdout.strip()}")
+    except Exception:
+        print("Git:     not available")
+
+    print()
+    files = list(collect_filesystem(root))
+    lang_counts: dict[str, int] = {}
+    total_tokens = 0
+    for path, content in files:
+        lang = detect_language(path) or "other"
+        lang_counts[lang] = lang_counts.get(lang, 0) + 1
+        total_tokens += count_tokens(content)
+
+    print(f"Files found: {len(files)}")
+    print(f"Estimated total tokens: {total_tokens:,}")
+    print()
+    print("By language:")
+    for lang, count in sorted(lang_counts.items(), key=lambda x: -x[1])[:10]:
+        bar = "█" * min(20, count)
+        print(f"  {lang:<15} {bar}  {count}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="ctxeng",
+        description="Build perfect LLM context from your codebase.",
+    )
+    parser.add_argument("--root", default=".", help="Project root (default: cwd)")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # --- build ---
+    build_p = sub.add_parser("build", help="Build context for a query")
+    build_p.add_argument("query", nargs="*", help="What you want the LLM to do")
+    build_p.add_argument("--model", "-m", default="claude-sonnet-4",
+                         help="Target model (default: claude-sonnet-4)")
+    build_p.add_argument("--fmt", "-f", default="xml",
+                         choices=["xml", "markdown", "plain"],
+                         help="Output format (default: xml)")
+    build_p.add_argument("--output", "-o", help="Write output to file instead of stdout")
+    build_p.add_argument("--only", nargs="+", metavar="PATTERN",
+                         help='Include only matching globs, e.g. "**/*.py"')
+    build_p.add_argument("--exclude", nargs="+", metavar="PATTERN",
+                         help="Exclude matching globs")
+    build_p.add_argument("--files", nargs="+", metavar="FILE",
+                         help="Explicit list of files to include")
+    build_p.add_argument("--git-diff", action="store_true",
+                         help="Only include git-changed files")
+    build_p.add_argument("--git-base", default="HEAD",
+                         help="Git base ref for diff (default: HEAD)")
+    build_p.add_argument("--system", help="System prompt text")
+    build_p.add_argument("--no-git", action="store_true",
+                         help="Disable git recency scoring")
+    build_p.add_argument("--budget", type=int,
+                         help="Override token budget total")
+    build_p.add_argument("--max-size", type=int, default=500,
+                         help="Max file size in KB (default: 500)")
+    build_p.set_defaults(func=cmd_build)
+
+    # --- info ---
+    info_p = sub.add_parser("info", help="Show project info and file stats")
+    info_p.set_defaults(func=cmd_info)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

ctxeng/core.py

@@ -0,0 +1,156 @@
+"""Main ContextEngine — the primary public API."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ctxeng.models import Context, ContextFile, TokenBudget
+from ctxeng.optimizer import count_tokens, detect_language, optimize_budget
+from ctxeng.scorer import rank_files
+from ctxeng.sources import collect_explicit, collect_filesystem, collect_git_changed
+
+
+class ContextEngine:
+    """
+    Build perfect LLM context from your codebase.
+
+    Example::
+
+        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())
+        # → paste ctx.to_string() into your LLM
+
+    Args:
+        root:               Root directory of your project (default: cwd).
+        model:              Target model name — used to set token budget.
+        budget:             Explicit TokenBudget, overrides `model`.
+        max_file_size_kb:   Skip files larger than this (default: 500 KB).
+        include_patterns:   Only include files matching these glob patterns.
+        exclude_patterns:   Skip files matching these glob patterns.
+        use_git:            Score files using git recency signal (default: True).
+    """
+
+    def __init__(
+        self,
+        root: str | Path = ".",
+        model: str = "claude-sonnet-4",
+        budget: TokenBudget | None = None,
+        max_file_size_kb: int = 500,
+        include_patterns: list[str] | None = None,
+        exclude_patterns: list[str] | None = None,
+        use_git: bool = True,
+    ) -> None:
+        self.root = Path(root).resolve()
+        self.model = model
+        self.budget = budget or TokenBudget.for_model(model)
+        self.max_file_size_kb = max_file_size_kb
+        self.include_patterns = include_patterns
+        self.exclude_patterns = exclude_patterns
+        self.use_git = use_git
+
+    def build(
+        self,
+        query: str = "",
+        *,
+        files: list[str | Path] | None = None,
+        git_diff: bool = False,
+        git_base: str = "HEAD",
+        system_prompt: str = "",
+        fmt: str = "xml",
+    ) -> Context:
+        """
+        Build and return a Context object optimized for your query.
+
+        Args:
+            query:          What you're asking the LLM to do. More specific = better scoring.
+            files:          Explicit list of files to include (bypasses auto-discovery).
+            git_diff:       Only include files changed since `git_base`.
+            git_base:       Git ref for diff base (default: HEAD).
+            system_prompt:  Optional system prompt (counts against token budget).
+            fmt:            Output format hint, passed through to Context.
+
+        Returns:
+            A :class:`Context` object. Call ``.to_string()`` to get the LLM-ready string,
+            or ``.summary()`` to see what was included and why.
+        """
+        # 1. Collect raw files
+        raw: list[tuple[Path, str]] = []
+
+        if files:
+            explicit_paths = [Path(f) for f in files]
+            raw.extend(collect_explicit(explicit_paths, self.root))
+        elif git_diff:
+            raw.extend(collect_git_changed(self.root, base=git_base))
+        else:
+            raw.extend(
+                collect_filesystem(
+                    self.root,
+                    max_file_size_kb=self.max_file_size_kb,
+                    include_patterns=self.include_patterns,
+                    exclude_patterns=self.exclude_patterns,
+                )
+            )
+
+        # 2. Score and rank
+        ranked = rank_files(raw, query, self.root)
+
+        # 3. Build ContextFile objects
+        context_files = [
+            ContextFile(
+                path=path,
+                content=content,
+                relevance_score=score,
+                language=detect_language(path),
+            )
+            for path, content, score in ranked
+        ]
+
+        # 4. Optimize for token budget
+        query_tokens = count_tokens(query, self.model) if query else 0
+        system_tokens = count_tokens(system_prompt, self.model) if system_prompt else 0
+
+        included, skipped = optimize_budget(
+            context_files,
+            self.budget,
+            query_tokens=query_tokens,
+            system_tokens=system_tokens,
+            model=self.model,
+        )
+
+        total_tokens = sum(f.token_count for f in included) + query_tokens + system_tokens
+
+        # 5. Gather metadata
+        metadata = self._gather_metadata()
+
+        return Context(
+            files=included,
+            system_prompt=system_prompt,
+            query=query,
+            total_tokens=total_tokens,
+            budget=self.budget,
+            skipped_files=skipped,
+            metadata=metadata,
+        )
+
+    def _gather_metadata(self) -> dict:
+        meta: dict = {"project_root": str(self.root)}
+        try:
+            import subprocess
+            r = subprocess.run(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                cwd=self.root, capture_output=True, text=True, timeout=2
+            )
+            if r.returncode == 0:
+                meta["git_branch"] = r.stdout.strip()
+            r2 = subprocess.run(
+                ["git", "log", "-1", "--format=%h %s"],
+                cwd=self.root, capture_output=True, text=True, timeout=2
+            )
+            if r2.returncode == 0:
+                meta["last_commit"] = r2.stdout.strip()
+        except Exception:
+            pass
+        return meta

ctxeng/integrations/__init__.py

@@ -0,0 +1,145 @@
+"""
+Drop-in integrations for popular LLM clients.
+
+These helpers take a Context object and call the LLM directly,
+so you never have to manually paste context again.
+
+Example (Claude)::
+
+    from ctxeng import ContextEngine
+    from ctxeng.integrations import ask_claude
+
+    engine = ContextEngine(".", model="claude-sonnet-4")
+    ctx = engine.build("Why is the login test failing?")
+    response = ask_claude(ctx)
+    print(response)
+
+Example (OpenAI)::
+
+    from ctxeng import ContextEngine
+    from ctxeng.integrations import ask_openai
+
+    engine = ContextEngine(".", model="gpt-4o")
+    ctx = engine.build("Refactor this to be async")
+    response = ask_openai(ctx)
+    print(response)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ctxeng.models import Context
+
+
+def ask_claude(
+    ctx: Context,
+    *,
+    api_key: str | None = None,
+    model: str | None = None,
+    max_tokens: int = 4096,
+    fmt: str = "xml",
+) -> str:
+    """
+    Send a Context to Anthropic's Claude API and return the response text.
+
+    Requires: ``pip install anthropic``
+
+    Args:
+        ctx:        The context built by ContextEngine or ContextBuilder.
+        api_key:    Anthropic API key. Falls back to ANTHROPIC_API_KEY env var.
+        model:      Model to use. Defaults to claude-sonnet-4-20250514.
+        max_tokens: Max response tokens (default 4096).
+        fmt:        Context rendering format ('xml' recommended for Claude).
+
+    Returns:
+        The assistant's response as a string.
+    """
+    try:
+        import anthropic
+    except ImportError:
+        raise ImportError(
+            "anthropic package required: pip install anthropic"
+        ) from None
+
+    client = anthropic.Anthropic(api_key=api_key) if api_key else anthropic.Anthropic()
+    model = model or "claude-sonnet-4-20250514"
+
+    messages = [{"role": "user", "content": ctx.to_string(fmt)}]
+
+    kwargs: dict = dict(model=model, max_tokens=max_tokens, messages=messages)
+    if ctx.system_prompt:
+        kwargs["system"] = ctx.system_prompt
+
+    response = client.messages.create(**kwargs)
+    return response.content[0].text
+
+
+def ask_openai(
+    ctx: Context,
+    *,
+    api_key: str | None = None,
+    model: str | None = None,
+    max_tokens: int = 4096,
+    fmt: str = "markdown",
+) -> str:
+    """
+    Send a Context to the OpenAI API and return the response text.
+
+    Requires: ``pip install openai``
+
+    Args:
+        ctx:        The context built by ContextEngine or ContextBuilder.
+        api_key:    OpenAI API key. Falls back to OPENAI_API_KEY env var.
+        model:      Model to use. Defaults to gpt-4o.
+        max_tokens: Max response tokens (default 4096).
+        fmt:        Context rendering format ('markdown' recommended for OpenAI).
+
+    Returns:
+        The assistant's response as a string.
+    """
+    try:
+        from openai import OpenAI
+    except ImportError:
+        raise ImportError(
+            "openai package required: pip install openai"
+        ) from None
+
+    client = OpenAI(api_key=api_key) if api_key else OpenAI()
+    model = model or "gpt-4o"
+
+    messages = []
+    if ctx.system_prompt:
+        messages.append({"role": "system", "content": ctx.system_prompt})
+    messages.append({"role": "user", "content": ctx.to_string(fmt)})
+
+    response = client.chat.completions.create(
+        model=model,
+        max_tokens=max_tokens,
+        messages=messages,
+    )
+    return response.choices[0].message.content or ""
+
+
+def to_langchain_messages(ctx: Context, fmt: str = "xml") -> list:
+    """
+    Convert a Context to a list of LangChain message objects.
+
+    Requires: ``pip install langchain-core``
+
+    Returns:
+        List of [SystemMessage?, HumanMessage] suitable for any LangChain chat model.
+    """
+    try:
+        from langchain_core.messages import HumanMessage, SystemMessage
+    except ImportError:
+        raise ImportError(
+            "langchain-core required: pip install langchain-core"
+        ) from None
+
+    messages = []
+    if ctx.system_prompt:
+        messages.append(SystemMessage(content=ctx.system_prompt))
+    messages.append(HumanMessage(content=ctx.to_string(fmt)))
+    return messages