Metadata-Version: 2.4
Name: agenticstackfile
Version: 0.2.1
Summary: Instant codebase map for AI agents — understand any project before making changes
Author-email: Rajat Handa <handarajat111@gmail.com>
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all
Requires-Dist: anthropic>=0.20.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: watchdog>=3.0.0; extra == "all"

# AgenticStack

Instant codebase map for AI agents — understand any Python project before making changes.

## What it does

AgenticStack analyzes your Python project and generates `AgenticStack.txt` — a structured file that tells any AI agent:

- Where every model, view, serializer, service, and utility lives
- Which files to touch when making a specific change
- How your project is structured by framework (Django, Flask, FastAPI, or plain Python)
- A step-by-step change guide using your actual file paths

## Installation

```bash
pip install agenticstackfile
```

With AI support:

```bash
pip install 'agenticstackfile[anthropic]'
pip install 'agenticstackfile[openai]'
```

With auto-sync (watch mode):

```bash
pip install 'agenticstackfile[watch]'
```

Everything at once:

```bash
pip install 'agenticstackfile[all]'
```

## Usage

```bash
agenticstack init      # First-time setup — creates config and ignore file
agenticstack update    # Manually refresh AgenticStack.txt
agenticstack watch     # Auto-sync mode — watches for file changes and syncs automatically
```

## Auto-sync (Watch Mode)

`agenticstack watch` runs two background services:

- **Watcher** — monitors your project for file changes in real time
- **Scheduler** — syncs `AgenticStack.txt` automatically based on your configured interval

Only syncs when files have actually changed — no wasted API tokens.

Requires `watchdog`: `pip install 'agenticstackfile[watch]'`

## Modes

**Static mode** — no API key needed. Uses Python AST to map your codebase for free.

**AI mode** — provide an API key and Claude or GPT generates rich, detailed documentation with change guides tailored to your framework.

## Configuration

Edit `.agenticstack.ini` in your project root:

```ini
[agenticstack]
provider = anthropic
model = default
api_key = YOUR_API_KEY
output_file = AgenticStack.txt
depth = standard
sync_trigger = false
sync_time = hourly
```

| Key | Values | Description |
|---|---|---|
| `provider` | `anthropic`, `openai` | AI provider to use |
| `model` | `default`, or model name | Model to use. `default` picks the best available. |
| `api_key` | your key | API key for AI mode |
| `output_file` | filename | Output file name |
| `depth` | `standard` | Analysis depth |
| `sync_trigger` | `true`, `false` | Enable auto-sync in watch mode |
| `sync_time` | `realtime`, `hourly`, `daily` | How often to sync when changes are detected |

## Ignoring Files

Create `.agenticstackignore` in your project root (auto-created by `agenticstack init`):
