Metadata-Version: 2.5
Name: build-ai-context
Version: 1.0.10
Summary: Export source code and project files into AI-friendly text bundles with manifest
Project-URL: Homepage, https://github.com/asjnaang/build-ai-context
Project-URL: Documentation, https://github.com/asjnaang/build-ai-context#readme
Project-URL: Repository, https://github.com/asjnaang/build-ai-context
Project-URL: Issues, https://github.com/asjnaang/build-ai-context/issues
Author: ASJN
License-Expression: MIT
License-File: LICENSE
Keywords: ai,code,copilot,export,llm,source-code,text
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: pathspec>=0.9.0
Requires-Dist: questionary>=1.10.0
Requires-Dist: rich>=10.0.0
Provides-Extra: all
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: graph
Requires-Dist: tree-sitter-language-pack>=0.7.2; extra == 'graph'
Description-Content-Type: text/markdown

# build-ai-context

Export source code and project files into AI-friendly text bundles with a compact manifest. Perfect for feeding your codebase to AI assistants like Claude, GPT-4, Copilot, or any LLM.

**Commands:** `build-ai-context` or `baic` (short alias)

## Why use this?

- **AI-Ready Output**: Bundles include metadata (file paths, line numbers, categories) so AI can precisely reference your code
- **Smart Filtering**: Automatically skips build artifacts, dependencies, secrets, and previously exported bundles
- **Flexible Selection**: 5 ways to select files - export everything, by category, by path, mixed, or by keywords in code
- **Continuous Workflow**: Stay in the tool - export, then export more files without restarting

## Quick Start

```bash
# Install
pip install build-ai-context

# Interactive mode (recommended for first use)
baic

# Non-interactive - export specific categories
baic . --non-interactive --categories python typescript
```

## Installation

```bash
pip install build-ai-context
```

Or for development:

```bash
git clone https://github.com/asjnaang/build-ai-context
cd build-ai-context
pip install -e .
```

## Interactive Mode (5 Ways to Select Files)

When you run `baic` without flags, you'll see an interactive menu. Choose how to select files:

### 1) all - Export Everything Supported
Export all supported files in your project. Simple and complete.

### 2) category - Pick by Language/Type
Select specific categories like `python`, `typescript`, `java_kotlin`, `shell`, etc.

```bash
# In interactive mode, choose option 2, then enter:
python,shell,config_docs
```

### 3) path - Pick Files/Folders by Path
Specify exact paths, filenames, or folder names:

```bash
# Non-interactive - handles spaces intelligently
baic . --non-interactive --paths src app tests

# Mixed commas and spaces work too
baic . --non-interactive --paths "main.py utils.py, helpers.py"
```

The tool intelligently parses paths even if you mix commas and spaces or omit separators.

### 4) mixed - Categories + Paths + Name Filters
Combine categories, paths, and filename filters:

```bash
# Select python files in src folder containing "auth" or "login"
# In interactive mode: choose 4, then enter categories, paths, and filters
```

### 5) keyword - Search Code Content
Search for keywords in your actual code and export files containing them:

```bash
# Non-interactive
baic . --non-interactive --keywords TODO FIXME,BUG,HACK

# Interactive - great for finding:
# - TODO/FIXME comments
# - Function names (e.g., "authenticate", "validate")
# - Error handling patterns
```

In interactive mode, you'll see a checkbox UI with all matching files pre-selected. Uncheck any files you don't want, then press Enter to bundle.

## CLI Options

| Option | Description | Example |
|--------|-------------|---------|
| `project_root` | Directory to scan (default: current) | `baic /path/to/project` |
| `--tree` | Generate filetree only, exit | `baic --tree .` |
| `--graph` | Generate code graph only (catalog + imports), exit | `baic --graph .` |
| `--format` | Graph file format: `txt` (default) or `json` | `--graph --format json` |
| `--categories` | Export by category | `--categories python typescript` |
| `--paths` | Export by path/filename | `--paths src tests` |
| `--keywords` | Search in code content | `--keywords TODO FIXME` |
| `--non-interactive` | Run without prompts | `--non-interactive` |
| `--max-file-lines` | Skip repo source files with ≥ N lines when bundling (default: 3000; `0` = no limit). Bundle output size stays fixed at 8000 lines. | `--max-file-lines 10000` |
| `--output-dir` | Custom output folder | `--output-dir ./my-bundles` |
| `--project-overview` | Generate architecture overview | `--project-overview` |
| `--include-secret-files` | Include .env, keys, etc. (careful!) | `--include-secret-files` |
| `--redact` | Redact secrets from output | `--redact` |
| `--version` | Show version | `--version` |

## Categories Supported

| Category | Extensions |
|----------|------------|
| `python` | `.py` |
| `typescript` | `.ts`, `.tsx` |
| `javascript` | `.js`, `.jsx`, `.mjs`, `.cjs` |
| `java_kotlin` | `.java`, `.kt`, `.kts`, `.gradle` |
| `ios_apple` | `.swift`, `.m`, `.h`, `.plist` |
| `web_ui` | `.html`, `.css`, `.scss`, `.vue`, `.svelte` |
| `shell` | `.sh`, `.bash`, `.zsh` |
| `flutter` | `.dart` |
| `config_docs` | `.json`, `.yaml`, `.toml`, `.md` |

### Category Aliases

Shortcuts you can use: `py`→`python`, `ts`→`typescript`, `js`→`javascript`, `android`→`java_kotlin`, `ios`→`ios_apple`, `web`→`web_ui`, `sh`→`shell`, `dart`→`flutter`

## Output Files

After running, you'll get:

| File | Description |
|------|-------------|
| `<project>_bundle_001_<timestamp>.txt`, ... | Text bundles with consistent timestamps |
| `<project>_manifest_<timestamp>.json` | Maps every file to its bundle and line numbers |
| `<project>_readme_<timestamp>.txt` | Quick summary of what was exported |
| `<project>_file_tree_<timestamp>.txt` | Path list (line + comma separated) and type counts |
| `<project>_code_graph_<timestamp>.txt` | (with `--graph`) Symbol catalog + import edges |
| `PROJECT_OVERVIEW.txt` | (with `--project-overview`) Architecture overview |

### Bundle Format

Each file in a bundle includes a header that AI assistants can use to locate code:

```
# ===== BEGIN FILE: src/utils/auth.py =====
# category : python
# chunk : 1/1
# line_range : 1-50
# total_lines : 50
# ===== CONTENT =====
def authenticate(user):
    ...
# ===== END FILE: src/utils/auth.py (chunk 1/1) =====
```

### MANIFEST.json Structure

```json
{
  "tool": "build-ai-context",
  "selected_files": ["src/main.py", "src/utils.py"],
  "selection": {
    "selection_mode": "category",
    "selected_categories": ["python"],
    "selected_paths": []
  },
  "bundles": [
    {
      "bundle": "bundle_001.txt",
      "files": [
        {
          "path": "src/main.py",
          "category": "python",
          "file_start_line": 1,
          "file_end_line": 50,
          "bundle_start_line": 10,
          "bundle_end_line": 59
        }
      ]
    }
  ]
}
```

## Filetree Feature

Generate a path list that AI agents can parse: one full relative path per line, each ending with a comma:

```bash
# Generate filetree only (quick project overview)
baic --tree .
baic --tree /path/to/project

# Filetree is automatically included in exports
baic . --non-interactive
```

Example filetree output:
```
root: myproject
file_count: 4

paths:
README.md,
main.py,
src/app.kt,
src/config.xml,

types:
config_docs: 2
java_kotlin: 1
python: 1
```

## Code graph

`baic --graph` writes a small map of the repo for AI agents: a per-file catalog of defs, plus import edges. Same flag style as `--tree`. One scan, then exit.

```bash
# Graph only (txt by default)
baic --graph .
baic --graph /path/to/project

# Same facts as JSON
baic --graph --format json .

# Tree + graph, one scan
baic --tree --graph .
```

Python is parsed with the stdlib `ast` module. TypeScript/JavaScript, Kotlin, Swift, Java, and Dart use tree-sitter when `build-ai-context[graph]` is installed (`pip install 'build-ai-context[graph]'`, Python 3.10+). Without that extra, those languages still get a heuristic catalog + imports so `--graph` never requires a native wheel.

Example:

```
root: myproject
file_count: 4
parsed: 3
skipped: 1
engine: ast, tree-sitter
languages: python=2, typescript=1

catalog:
src/cli.py:
  rank: 0.4120,
  fn: main @12,
  fn: run_exporter @40,
src/models.py:
  rank: 0.1881,
  class: SourceFile @14,

imports:
src/cli.py --> src/exporter.py,
src/cli.py --> src/models.py,
```

Catalog files are ordered by PageRank on local import edges (same idea as Aider's repo map): hubs other files import show up first. Each def includes its line so an agent can jump there. `--format json` is the same payload for tools.

This is not a full call graph. Local imports are resolved to project files when we can; third-party / stdlib names stay as module strings.

## Redaction

By default, redaction is **disabled** to preserve code integrity. Enable it when sharing with external parties:

```bash
# Without redaction (default) - code stays intact
baic . --non-interactive

# With redaction - secrets are replaced with <REDACTED>
baic . --non-interactive --redact
```

Redaction targets: API keys, tokens, passwords, JWTs, AWS keys, GitHub tokens, etc.

## What Gets Excluded

### Automatically Skipped (No config needed)

- **Directories**: `.git`, `node_modules`, `__pycache__`, `.gradle`, `build`, `dist`, `target`, `.github`
- **Exported bundles**: `exported_sources*` folders (prevents re-bundling previous exports)
- **Lock files**: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
- **System files**: `.DS_Store`, `thumbs.db`, `*.swp`

### Large Files

- **>= 1500 lines**: Exported with a warning (may need cleanup)
- **>= 3000 lines**: Skipped automatically (shown separately for manual handling)

### Secrets (Skipped by default, include with `--include-secret-files`)

- `.env` files and variants
- Private keys (`*.pem`, `*.key`, `id_rsa`)
- Certificates, keystores, Firebase configs

## Usage Examples

### Export Python code for Claude/GPT review

```bash
baic /my-project --non-interactive --categories python --project-overview
```

### Find all files with TODO comments

```bash
# Interactive
baic
# Choose option 5, enter: TODO

# Or non-interactive
baic . --non-interactive --keywords TODO
```

### Export specific folders

```bash
baic . --non-interactive --paths src/components src/utils
```

### Full export with overview

```bash
baic /path/to/project \
    --non-interactive \
    --categories python typescript web_ui \
    --max-file-lines 10000 \
    --project-overview \
    --output-dir ./ai-review-bundles
```

### Stay in the tool for multiple exports

```bash
baic
# Export python files...
# When asked "Do you want to export more files?" answer Y
# Export shell scripts...
# Answer N to exit
```

## Using with AI Assistants

1. **Run the exporter**: `baic . --categories python`
2. **Upload bundles**: Attach `bundle_001.txt`, `bundle_002.txt`, etc.
3. **Upload manifest**: Attach `MANIFEST.json` so AI understands file mappings
4. **Ask away**: The AI can now reference exact file paths and line numbers

Example prompt to AI:
> "I've uploaded my Python project. Using the MANIFEST.json, find the authentication logic in src/auth.py and help me add password reset functionality."

## CLI Reference

```
usage: build-ai-context [-h] [--max-file-lines N] [--output-dir OUTPUT_DIR]
                       [--non-interactive] [--categories [CATEGORIES ...]]
                       [--paths [PATHS ...]] [--keywords [KEYWORDS ...]]
                       [--include-secret-files] [--project-overview]
                       [--tree] [--graph] [--format {txt,json}] [--redact] [--version]
                       [project_root]

positional arguments:
  project_root          Project root to scan (default: current directory)

options:
  -h, --help            Show help message
  --version             Show version
  --tree                Generate filetree only and exit
  --graph               Generate code graph (catalog + imports) and exit
  --format {txt,json}   Graph file format (default: txt)
  --redact              Redact secrets from output (default: disabled)
  --max-file-lines N    Skip repo source files with >= N lines (default: 3000;
                        0 disables the per-file limit). Output bundles are
                        always packed to 8000 lines max.
  --output-dir DIR      Custom output directory
  --non-interactive     Run without prompts
  --categories CATS     Categories to export
  --paths PATHS         Files/folders to export
  --keywords KEYWORDS   Keywords to search in file content
  --include-secret-files Include secret-like files
  --project-overview    Generate PROJECT_OVERVIEW.txt
```

## Contributing

Contributions welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.
