contextzip 0.3.2__tar.gz → 0.3.3__tar.gz

{contextzip-0.3.2 → contextzip-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.2
+Version: 0.3.3
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -148,6 +148,40 @@ contextzip --output ~/Desktop/project-context.zip
 
 ---
 
+## Python API
+
+contextzip is also usable as a library. All CLI capabilities are available as plain Python functions — no Click, no Rich output, no `SystemExit`.
+
+```python
+from contextzip import get_git_changes, get_files, create_zip
+
+# Get changed files and use them directly
+collection = get_git_changes()
+for f in collection.files:          # plain pathlib.Path objects
+    upload(f)                       # no zip required
+
+# Or zip them and upload the archive
+pkg = create_zip(collection, output="/tmp/changes.zip")
+with open(pkg.zip_path, "rb") as f:
+    upload_to_s3(f)
+
+# Full project scan with filters
+collection = get_files(include=["src/"], exclude=["tests/"])
+pkg = create_zip(collection, output="/tmp/upload.zip")
+print(f"{pkg.file_count} files, {pkg.compressed_bytes} bytes")
+```
+
+| Function | Description |
+|---|---|
+| `get_git_changes(path?)` | Modified, added, and untracked files from git |
+| `get_files(path?, include?, exclude?)` | All project files after exclusion rules |
+| `create_zip(collection, output?)` | Write a `FileCollection` to a ZIP archive |
+| `detect_ecosystem(path?)` | Detect framework and confidence level |
+
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
+
+---
+
 ## AI-powered file selection
 
 The `--prompt` flag lets you describe a task in plain English. contextzip scans your project, builds a lightweight file map, and asks Gemini to return the minimum set of files needed for that task — typically 2–5, never more than 10. The result is a tightly scoped ZIP with only what you'd actually open to make the change.

{contextzip-0.3.2 → contextzip-0.3.3}/README.md

@@ -119,6 +119,40 @@ contextzip --output ~/Desktop/project-context.zip
 
 ---
 
+## Python API
+
+contextzip is also usable as a library. All CLI capabilities are available as plain Python functions — no Click, no Rich output, no `SystemExit`.
+
+```python
+from contextzip import get_git_changes, get_files, create_zip
+
+# Get changed files and use them directly
+collection = get_git_changes()
+for f in collection.files:          # plain pathlib.Path objects
+    upload(f)                       # no zip required
+
+# Or zip them and upload the archive
+pkg = create_zip(collection, output="/tmp/changes.zip")
+with open(pkg.zip_path, "rb") as f:
+    upload_to_s3(f)
+
+# Full project scan with filters
+collection = get_files(include=["src/"], exclude=["tests/"])
+pkg = create_zip(collection, output="/tmp/upload.zip")
+print(f"{pkg.file_count} files, {pkg.compressed_bytes} bytes")
+```
+
+| Function | Description |
+|---|---|
+| `get_git_changes(path?)` | Modified, added, and untracked files from git |
+| `get_files(path?, include?, exclude?)` | All project files after exclusion rules |
+| `create_zip(collection, output?)` | Write a `FileCollection` to a ZIP archive |
+| `detect_ecosystem(path?)` | Detect framework and confidence level |
+
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
+
+---
+
 ## AI-powered file selection
 
 The `--prompt` flag lets you describe a task in plain English. contextzip scans your project, builds a lightweight file map, and asks Gemini to return the minimum set of files needed for that task — typically 2–5, never more than 10. The result is a tightly scoped ZIP with only what you'd actually open to make the change.

{contextzip-0.3.2 → contextzip-0.3.3}/contextzip/__init__.py

@@ -1,6 +1,6 @@
 """contextzip — intelligent codebase packager for AI tools."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 
 from contextzip.api import (
     FileCollection,

contextzip-0.3.3/contextzip/ai/__init__.py

@@ -0,0 +1 @@
+"""contextzip.ai — AI-powered file selection for --prompt mode."""

contextzip-0.3.3/contextzip/ai/gemini.py

@@ -0,0 +1,282 @@
+"""
+ai/gemini.py — Thin Gemini API client for contextzip's prompt-aware mode.
+
+Makes a single POST to the Gemini generateContent endpoint and returns
+a ranked list of file paths relevant to the user's task description.
+
+Design principles:
+  - Raw httpx calls only — no Google SDK dependency
+  - Strict JSON output from the model — no markdown, no prose
+  - Validates every returned path against the real file tree
+  - Single responsibility: call API, parse response, validate paths
+"""
+
+from __future__ import annotations
+
+import json
+
+try:
+    import httpx
+
+    _HTTPX_AVAILABLE = True
+except ImportError:
+    _HTTPX_AVAILABLE = False
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_API_URL = (
+    "https://generativelanguage.googleapis.com/v1beta/models"
+    "/{model}:generateContent?key={key}"
+)
+
+DEFAULT_MODEL = "gemini-2.5-flash-lite"
+
+# Hard cap: never return more than this many files regardless of model output.
+# Minimum context is the goal — the prompt enforces this, but we double-guard.
+_MAX_FILES = 12
+
+_TIMEOUT_SECONDS = 30
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class GeminiError(Exception):
+    """Raised when the Gemini API call fails for any reason."""
+
+
+class GeminiUnavailable(GeminiError):
+    """Raised when httpx is not installed."""
+
+
+class GeminiRateLimitError(GeminiError):
+    """Raised specifically on HTTP 429 — allows callers to trigger fallback."""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def select_files(
+    *,
+    api_key: str,
+    prompt: str,
+    file_tree: list[tuple[str, int]],  # [(rel_path, size_bytes), ...]
+    ecosystem: str,
+    model: str = DEFAULT_MODEL,
+) -> list[str]:
+    """
+    Ask Gemini which files are relevant to *prompt* and return their paths.
+
+    Parameters
+    ----------
+    api_key:
+        Gemini API key from Google AI Studio.
+    prompt:
+        The user's natural-language task description.
+    file_tree:
+        All candidate files as (relative_posix_path, size_bytes) tuples.
+        These should already have contextzip's standard exclusions applied —
+        no node_modules, no build artifacts, no .env files.
+    ecosystem:
+        Human-readable detected framework string, e.g. "Next.js + TypeScript".
+        Gives the model important context for relevance scoring.
+    model:
+        Gemini model identifier. Defaults to gemini-2.5-flash-lite.
+
+    Returns
+    -------
+    list[str]
+        Relative POSIX paths of the selected files, ordered by relevance
+        (most relevant first). Always a strict subset of the input file_tree
+        paths — hallucinated or non-existent paths are silently dropped.
+
+    Raises
+    ------
+    GeminiUnavailable
+        If httpx is not installed.
+    GeminiError
+        On any API or parsing failure.
+    """
+    if not _HTTPX_AVAILABLE:
+        raise GeminiUnavailable(
+            "httpx is required for AI-powered selection. "
+            "Install it with: pip install httpx"
+        )
+
+    system_prompt = _build_system_prompt()
+    user_message = _build_user_message(prompt, file_tree, ecosystem)
+
+    url = _API_URL.format(model=model, key=api_key)
+
+    payload = {
+        "contents": [
+            {
+                "role": "user",
+                "parts": [{"text": f"{system_prompt}\n\n{user_message}"}],
+            }
+        ],
+        "generationConfig": {
+            "temperature": 0.0,  # deterministic — this is a ranking task
+            "maxOutputTokens": 512,  # a list of paths needs very few tokens
+            "responseMimeType": "application/json",
+        },
+    }
+
+    try:
+        response = httpx.post(url, json=payload, timeout=_TIMEOUT_SECONDS)
+    except httpx.TimeoutException:
+        raise GeminiError("Request timed out after 30 seconds.")
+    except httpx.RequestError as exc:
+        raise GeminiError(f"Network error: {exc}")
+
+    if response.status_code == 400:
+        raise GeminiError("Invalid request — check your API key format.")
+    if response.status_code == 401 or response.status_code == 403:
+        raise GeminiError(
+            "API key rejected. Run [cyan]contextzip config --reset-key[/] to update it."
+        )
+    if response.status_code == 429:
+        raise GeminiRateLimitError(
+            "Rate limit reached on the free tier (15 req/min). "
+            "Wait a moment and try again, or your new key may still be activating — "
+            "Google can take up to 60 seconds after key creation."
+        )
+    if response.status_code != 200:
+        raise GeminiError(
+            f"Gemini API returned HTTP {response.status_code}: {response.text[:200]}"
+        )
+
+    return _parse_response(response.json(), file_tree)
+
+
+# ---------------------------------------------------------------------------
+# Prompt construction
+# ---------------------------------------------------------------------------
+
+
+def _build_system_prompt() -> str:
+    return """\
+You are a precise file relevance assistant for software projects.
+
+Your only job: given a developer's task description and a project file tree,
+return the MINIMUM set of files a developer would need to open to complete
+that task. Think like a senior engineer doing a surgical code change —
+open only what you must touch or read to understand the change.
+
+Rules you must follow:
+- Return ONLY a JSON array of file path strings. No explanation, no markdown,
+  no extra keys. Example: ["src/auth.ts", "components/Toast.tsx"]
+- Be ruthless about exclusion. If a file is not directly relevant to the
+  stated task, leave it out. Err heavily on the side of fewer files.
+- Prefer files that will be MODIFIED over files that are merely referenced.
+- Config files, test files, and documentation should only appear if the
+  task explicitly concerns them.
+- Never return more than 10 files. For most tasks 2–5 files is correct.
+- Order by relevance: most directly relevant file first.\
+"""
+
+
+def _build_user_message(
+    prompt: str,
+    file_tree: list[tuple[str, int]],
+    ecosystem: str,
+) -> str:
+    tree_lines = "\n".join(f"{path} ({_human_size(size)})" for path, size in file_tree)
+    return f"""\
+Framework: {ecosystem}
+
+Task: {prompt}
+
+Project files (exclusions already applied):
+{tree_lines}
+
+Return only a JSON array of the most relevant file paths for this task.\
+"""
+
+
+# ---------------------------------------------------------------------------
+# Response parsing and validation
+# ---------------------------------------------------------------------------
+
+
+def _parse_response(
+    data: dict,
+    file_tree: list[tuple[str, int]],
+) -> list[str]:
+    """
+    Extract and validate the file list from the Gemini API response.
+
+    - Parses the JSON array from the model's text output
+    - Drops any path the model hallucinated (not in the real file tree)
+    - Enforces the _MAX_FILES hard cap
+    - Warns (via exception) if the model returned mostly invalid paths
+    """
+    # Navigate the Gemini response structure
+    try:
+        text = data["candidates"][0]["content"]["parts"][0]["text"]
+    except (KeyError, IndexError) as exc:
+        raise GeminiError(f"Unexpected API response structure: {exc}\n{data}")
+
+    # Strip any accidental markdown fences the model might add
+    text = text.strip().strip("`").strip()
+    if text.startswith("json"):
+        text = text[4:].strip()
+
+    try:
+        raw_paths: list = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise GeminiError(
+            f"Model returned non-JSON output: {exc}\nRaw output: {text[:300]}"
+        )
+
+    if not isinstance(raw_paths, list):
+        raise GeminiError(
+            f"Expected a JSON array, got {type(raw_paths).__name__}: {text[:200]}"
+        )
+
+    # Build a set of valid paths for O(1) lookup
+    valid_paths: set[str] = {path for path, _ in file_tree}
+
+    validated: list[str] = []
+    hallucinated = 0
+
+    for item in raw_paths:
+        if not isinstance(item, str):
+            continue
+        # Normalise separators (model may return backslashes on Windows prompts)
+        normalised = item.replace("\\", "/").strip()
+        if normalised in valid_paths:
+            validated.append(normalised)
+        else:
+            hallucinated += 1
+
+    # Warn if the model was mostly making things up
+    total_returned = len(raw_paths)
+    if total_returned > 0 and hallucinated / total_returned > 0.5:
+        raise GeminiError(
+            f"Model returned {hallucinated}/{total_returned} non-existent paths. "
+            "This may indicate a model or prompt issue. Try a more specific prompt."
+        )
+
+    # Enforce hard cap
+    return validated[:_MAX_FILES]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _human_size(n: int) -> str:
+    for unit in ("B", "KB", "MB"):
+        if n < 1024:
+            return f"{n:.0f} {unit}"
+        n /= 1024
+    return f"{n:.1f} GB"

contextzip-0.3.3/contextzip/ai/heuristic.py

@@ -0,0 +1,333 @@
+"""
+ai/heuristic.py — Keyword-based file relevance scorer.
+
+Used as a fallback when the Gemini API is unavailable (rate limit, network
+error, no key). Scores each file purely from the prompt text and file path —
+no API calls, no dependencies beyond stdlib.
+
+This is intentionally simple and transparent. It will never be as accurate
+as Gemini, but it is always available and produces reasonable results for
+common cases like "update the login page" or "fix the toast component".
+
+Scoring model
+─────────────
+Each file receives a score based on:
+
+  1. Token overlap  — how many meaningful words from the prompt appear in
+                      the file's path components (stem + parent dirs).
+                      Longer matches score higher.
+
+  2. Directory bias — source-like directories (src/, app/, lib/, components/,
+                      utils/, routes/, pages/, server/, api/) score higher.
+                      Test and documentation directories score lower.
+
+  3. Extension bias — code files score higher than config, lock, or data files.
+
+Files with a score of zero are excluded entirely. The top-N results are
+returned, where N is capped at MAX_FILES.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+# Never return more files than this regardless of score
+MAX_FILES = 8
+
+# Words that carry no signal — filtered out before scoring
+_STOPWORDS = frozenset(
+    {
+        "i",
+        "a",
+        "an",
+        "the",
+        "to",
+        "in",
+        "on",
+        "at",
+        "of",
+        "for",
+        "and",
+        "or",
+        "but",
+        "is",
+        "it",
+        "be",
+        "do",
+        "my",
+        "this",
+        "that",
+        "with",
+        "from",
+        "want",
+        "need",
+        "make",
+        "update",
+        "change",
+        "fix",
+        "add",
+        "get",
+        "use",
+        "set",
+        "new",
+        "old",
+        "file",
+        "code",
+        "function",
+        "method",
+        "class",
+        "variable",
+    }
+)
+
+# Directory names that suggest source code worth including
+_SOURCE_DIRS = frozenset(
+    {
+        "src",
+        "app",
+        "lib",
+        "libs",
+        "components",
+        "component",
+        "utils",
+        "util",
+        "helpers",
+        "helper",
+        "routes",
+        "route",
+        "pages",
+        "page",
+        "server",
+        "api",
+        "services",
+        "service",
+        "hooks",
+        "hook",
+        "store",
+        "stores",
+        "context",
+        "contexts",
+        "middleware",
+        "handlers",
+        "handler",
+        "controllers",
+        "controller",
+        "views",
+        "view",
+        "models",
+        "model",
+        "core",
+        "common",
+        "shared",
+    }
+)
+
+# Directory names that suggest low relevance for most coding tasks
+_NOISE_DIRS = frozenset(
+    {
+        "test",
+        "tests",
+        "__tests__",
+        "spec",
+        "specs",
+        "docs",
+        "doc",
+        "documentation",
+        "examples",
+        "example",
+        "fixtures",
+        "mocks",
+        "mock",
+        "stubs",
+        "stub",
+        "scripts",
+        "bin",
+        "dist",
+        "build",
+        "out",
+        "coverage",
+    }
+)
+
+# Extensions that suggest runnable/editable source code
+_CODE_EXTENSIONS = frozenset(
+    {
+        ".py",
+        ".ts",
+        ".tsx",
+        ".js",
+        ".jsx",
+        ".go",
+        ".rs",
+        ".rb",
+        ".java",
+        ".kt",
+        ".swift",
+        ".cs",
+        ".cpp",
+        ".c",
+        ".h",
+        ".vue",
+        ".svelte",
+        ".astro",
+    }
+)
+
+# Extensions that are config-like (lower relevance unless prompt mentions them)
+_CONFIG_EXTENSIONS = frozenset(
+    {
+        ".json",
+        ".toml",
+        ".yaml",
+        ".yml",
+        ".ini",
+        ".cfg",
+        ".env",
+        ".md",
+        ".txt",
+        ".lock",
+        ".sum",
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def select_files(
+    *,
+    prompt: str,
+    file_tree: list[tuple[str, int]],
+) -> list[str]:
+    """
+    Score and rank *file_tree* entries by relevance to *prompt*.
+
+    Parameters
+    ----------
+    prompt:
+        The user's natural-language task description.
+    file_tree:
+        Candidate files as (relative_posix_path, size_bytes) tuples.
+        Standard exclusions must already have been applied by the caller.
+
+    Returns
+    -------
+    list[str]
+        Relative POSIX paths of the top-scoring files, best first.
+        Files scoring zero are excluded. Result is capped at MAX_FILES.
+    """
+    tokens = _tokenize(prompt)
+    if not tokens:
+        # Degenerate prompt — return nothing rather than random files
+        return []
+
+    scored: list[tuple[float, str]] = []
+
+    for rel_path, size_bytes in file_tree:
+        score = _score(rel_path, tokens, size_bytes)
+        if score > 0:
+            scored.append((score, rel_path))
+
+    # Sort descending by score, then alphabetically for determinism on ties
+    scored.sort(key=lambda x: (-x[0], x[1]))
+
+    return [path for _, path in scored[:MAX_FILES]]
+
+
+# ---------------------------------------------------------------------------
+# Scoring
+# ---------------------------------------------------------------------------
+
+
+def _score(rel_path: str, tokens: set[str], size_bytes: int) -> float:
+    """Compute a relevance score for a single file path."""
+    path = Path(rel_path)
+    stem = path.stem.lower()
+    suffix = path.suffix.lower()
+    parts = [p.lower() for p in path.parts]
+    dirs = parts[:-1]  # everything except the filename itself
+
+    score = 0.0
+
+    # ── 1. Token overlap ─────────────────────────────────────────────────────
+    # Split the stem by common separators (camelCase, kebab-case, snake_case)
+    stem_words = set(_split_identifier(stem))
+    dir_words: set[str] = set()
+    for d in dirs:
+        dir_words.update(_split_identifier(d))
+
+    # Direct hits in filename stem score highest
+    stem_hits = tokens & stem_words
+    score += len(stem_hits) * 3.0
+
+    # Partial substring matches in stem (e.g. "toast" in "useToast")
+    for token in tokens:
+        if len(token) >= 4 and token in stem and token not in stem_hits:
+            score += 1.0
+
+    # Hits in parent directory names score lower
+    dir_hits = tokens & dir_words
+    score += len(dir_hits) * 1.5
+
+    # No token overlap at all → zero score, file is irrelevant
+    if score == 0.0:
+        return 0.0
+
+    # ── 2. Directory bias ────────────────────────────────────────────────────
+    dir_set = set(dirs)
+    if dir_set & _SOURCE_DIRS:
+        score *= 1.4
+    if dir_set & _NOISE_DIRS:
+        score *= 0.4
+
+    # ── 3. Extension bias ────────────────────────────────────────────────────
+    if suffix in _CODE_EXTENSIONS:
+        score *= 1.2
+    elif suffix in _CONFIG_EXTENSIONS:
+        score *= 0.7
+
+    # ── 4. Penalise very large files ─────────────────────────────────────────
+    # Files over 100 KB are less likely to be what you want to change
+    if size_bytes > 100_000:
+        score *= 0.6
+
+    return score
+
+
+# ---------------------------------------------------------------------------
+# Text helpers
+# ---------------------------------------------------------------------------
+
+
+def _tokenize(text: str) -> set[str]:
+    """
+    Extract meaningful lowercase tokens from *text*.
+
+    - Splits on whitespace and punctuation
+    - Removes stopwords
+    - Keeps only tokens of 3+ characters
+    """
+    raw = re.findall(r"[a-zA-Z]+", text.lower())
+    return {w for w in raw if len(w) >= 3 and w not in _STOPWORDS}
+
+
+def _split_identifier(name: str) -> list[str]:
+    """
+    Split a file/directory name into component words.
+
+    Handles: kebab-case, snake_case, camelCase, PascalCase.
+
+    Examples:
+        "LoginPage"   → ["login", "page"]
+        "use-toast"   → ["use", "toast"]
+        "auth_utils"  → ["auth", "utils"]
+        "apiClient"   → ["api", "client"]
+    """
+    # Insert space before uppercase letters following lowercase (camelCase)
+    spaced = re.sub(r"([a-z])([A-Z])", r"\1 \2", name)
+    # Split on non-alphanumeric separators
+    parts = re.split(r"[^a-zA-Z0-9]+", spaced)
+    return [p.lower() for p in parts if p]

contextzip-0.3.3/contextzip/ai/selector.py

@@ -0,0 +1,158 @@
+"""
+ai/selector.py — Orchestrates AI-powered file selection for --prompt mode.
+
+Responsibilities:
+  1. Build a lean project map from the already-filtered file list
+  2. Call the Gemini client (with heuristic fallback on rate limit)
+  3. Return the selected subset as Path objects ready for packaging
+  4. Generate the prompt.txt content to include in the ZIP
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from contextzip.ai.gemini import select_files, GeminiRateLimitError
+from contextzip.filters import ResolveResult
+
+# Sentinels — tell the CLI which selection path was taken
+USED_GEMINI = "gemini"
+USED_HEURISTIC = "heuristic"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def ai_select(
+    *,
+    resolved: ResolveResult,
+    project_dir: Path,
+    prompt: str,
+    ecosystem: str,
+    api_key: str,
+) -> tuple[list[Path], str, str]:
+    """
+    Select the minimum relevant files for *prompt* from *resolved.included*.
+
+    Returns
+    -------
+    (selected_paths, prompt_txt, method)
+        selected_paths : list[Path] of absolute paths chosen
+        prompt_txt     : string content ready to write as prompt.txt in the ZIP
+        method         : USED_GEMINI or USED_HEURISTIC
+    """
+    from contextzip.ai import heuristic as _heuristic
+
+    file_tree = _build_file_tree(resolved.included, project_dir)
+    method = USED_GEMINI
+
+    try:
+        selected_rel = select_files(
+            api_key=api_key,
+            prompt=prompt,
+            file_tree=file_tree,
+            ecosystem=ecosystem,
+        )
+    except GeminiRateLimitError:
+        # Confirmed HTTP 429 only — fall back to keyword heuristic
+        selected_rel = _heuristic.select_files(
+            prompt=prompt,
+            file_tree=file_tree,
+        )
+        method = USED_HEURISTIC
+    # All other GeminiErrors (bad key, network, unexpected status) propagate
+    # up to _run_ai_selection in cli.py which displays the error and exits.
+
+    # Map relative path strings back to absolute Path objects
+    rel_to_abs: dict[str, Path] = {
+        p.relative_to(project_dir).as_posix(): p for p in resolved.included
+    }
+    selected_paths = [rel_to_abs[rel] for rel in selected_rel if rel in rel_to_abs]
+
+    prompt_txt = _build_prompt_txt(prompt, selected_rel, ecosystem, method)
+
+    return selected_paths, prompt_txt, method
+
+
+def build_prompt_only_txt(prompt: str, ecosystem: str) -> str:
+    """Build a minimal prompt.txt when no AI selection was performed."""
+    return _build_prompt_txt(prompt, [], ecosystem, USED_GEMINI)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_file_tree(
+    included: list[Path],
+    project_dir: Path,
+) -> list[tuple[str, int]]:
+    """
+    Convert the included file list into (relative_posix_path, size_bytes) tuples.
+
+    Binary files and files that can't be stat'd are silently skipped —
+    the model can't reason about them anyway.
+    """
+    tree: list[tuple[str, int]] = []
+
+    for abs_path in included:
+        try:
+            rel = abs_path.relative_to(project_dir).as_posix()
+            size = abs_path.stat().st_size
+        except (ValueError, OSError):
+            continue
+
+        if _is_binary(abs_path):
+            continue
+
+        tree.append((rel, size))
+
+    return tree
+
+
+def _build_prompt_txt(
+    prompt: str,
+    selected_rel: list[str],
+    ecosystem: str,
+    method: str,
+) -> str:
+    """
+    Build the prompt.txt to include inside the ZIP.
+
+    Any AI tool that receives the ZIP immediately sees the task description,
+    the framework, and exactly which files were selected and why.
+    """
+
+    selector_label = (
+        "contextzip AI (Gemini)"
+        if method == USED_GEMINI
+        else "contextzip (keyword heuristic — Gemini was rate limited)"
+    )
+
+    lines: list[str] = [
+        f"Task: {prompt}",
+        "",
+        f"Framework: {ecosystem}",
+        "",
+    ]
+
+    if selected_rel:
+        lines.append(f"Files selected by {selector_label}:")
+        for rel in selected_rel:
+            lines.append(f"  - {rel}")
+    else:
+        lines.append("(No files selected)")
+
+    return "\n".join(lines) + "\n"
+
+
+def _is_binary(path: Path, peek: int = 512) -> bool:
+    """Return True if the file appears to be binary (null bytes in first peek bytes)."""
+    try:
+        with path.open("rb") as fh:
+            return b"\x00" in fh.read(peek)
+    except OSError:
+        return False

{contextzip-0.3.2 → contextzip-0.3.3}/contextzip.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.2
+Version: 0.3.3
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -148,6 +148,40 @@ contextzip --output ~/Desktop/project-context.zip
 
 ---
 
+## Python API
+
+contextzip is also usable as a library. All CLI capabilities are available as plain Python functions — no Click, no Rich output, no `SystemExit`.
+
+```python
+from contextzip import get_git_changes, get_files, create_zip
+
+# Get changed files and use them directly
+collection = get_git_changes()
+for f in collection.files:          # plain pathlib.Path objects
+    upload(f)                       # no zip required
+
+# Or zip them and upload the archive
+pkg = create_zip(collection, output="/tmp/changes.zip")
+with open(pkg.zip_path, "rb") as f:
+    upload_to_s3(f)
+
+# Full project scan with filters
+collection = get_files(include=["src/"], exclude=["tests/"])
+pkg = create_zip(collection, output="/tmp/upload.zip")
+print(f"{pkg.file_count} files, {pkg.compressed_bytes} bytes")
+```
+
+| Function | Description |
+|---|---|
+| `get_git_changes(path?)` | Modified, added, and untracked files from git |
+| `get_files(path?, include?, exclude?)` | All project files after exclusion rules |
+| `create_zip(collection, output?)` | Write a `FileCollection` to a ZIP archive |
+| `detect_ecosystem(path?)` | Detect framework and confidence level |
+
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
+
+---
+
 ## AI-powered file selection
 
 The `--prompt` flag lets you describe a task in plain English. contextzip scans your project, builds a lightweight file map, and asks Gemini to return the minimum set of files needed for that task — typically 2–5, never more than 10. The result is a tightly scoped ZIP with only what you'd actually open to make the change.

{contextzip-0.3.2 → contextzip-0.3.3}/contextzip.egg-info/SOURCES.txt

@@ -21,6 +21,10 @@ contextzip.egg-info/dependency_links.txt
 contextzip.egg-info/entry_points.txt
 contextzip.egg-info/requires.txt
 contextzip.egg-info/top_level.txt
+contextzip/ai/__init__.py
+contextzip/ai/gemini.py
+contextzip/ai/heuristic.py
+contextzip/ai/selector.py
 contextzip/rules/__init__.py
 contextzip/rules/base.py
 contextzip/rules/go.py

{contextzip-0.3.2 → contextzip-0.3.3}/contextzip.egg-info/top_level.txt

@@ -1 +1,2 @@
 contextzip
+dist

{contextzip-0.3.2 → contextzip-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "contextzip"
-version = "0.3.2"
+version = "0.3.3"
 description = "Intelligently package your codebase for AI tools"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -43,4 +43,3 @@ contextzip = "contextzip.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["."]
-include = ["contextzip", "contextzip.rules", "contextzip.rules.errors"]