Metadata-Version: 2.4
Name: aipromptbucket
Version: 0.1.0
Summary: Python SDK for AI Prompt Bucket — managed prompt registry for teams
Project-URL: Homepage, https://aipromptbucket.com
Project-URL: Repository, https://github.com/Brightwing-Systems-LLC/aipromptbucket-python
Project-URL: Documentation, https://aipromptbucket.com/docs/sdks/python
Project-URL: Bug Tracker, https://github.com/Brightwing-Systems-LLC/aipromptbucket-python/issues
Project-URL: Changelog, https://github.com/Brightwing-Systems-LLC/aipromptbucket-python/blob/main/CHANGELOG.md
Author-email: Bright Wing Solutions LLC <support@brightwingsolutions.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,llm,prompt-management,prompts,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# AI Prompt Bucket — Python SDK

Python SDK for [AI Prompt Bucket](https://aipromptbucket.com), a managed prompt registry for teams.

## Installation

```bash
pip install aipromptbucket
```

Or with uv:

```bash
uv add aipromptbucket
```

## Configuration

Set environment variables or pass directly to the client:

```bash
export AIPROMPTBUCKET_API_KEY="sk-api01-your-key-here"
export AIPROMPTBUCKET_URL="https://aipromptbucket.com"  # optional, this is the default
```

## Quick Start — `get_prompt()`

The simplest way to use AI Prompt Bucket. One function, no boilerplate:

```python
from aipromptbucket import get_prompt

# Fetch a rendered prompt
text = get_prompt("my-prompt")

# With variables
text = get_prompt("my-prompt", variables={"name": "Alice"})

# With a specific label
text = get_prompt("my-prompt", label="staging")

# With a fallback if the service is unreachable
text = get_prompt("my-prompt", fallback="You are a helpful assistant.")

# With TTL caching (seconds)
text = get_prompt("my-prompt", ttl=300)
```

Set global defaults so you don't repeat yourself:

```python
import aipromptbucket

aipromptbucket.configure(
    api_key="sk-api01-...",
    base_url="https://aipromptbucket.com",
    default_label="production",
    default_ttl=300,
)
```

## Using the Full Client

For advanced use cases (creating prompts, managing versions, labels, etc.):

```python
from aipromptbucket import Client

client = Client()

# List all prompts
result = client.list_prompts()
if result.ok:
    for prompt in result.data:
        print(f"{prompt.slug}: {prompt.name}")

# Get a specific prompt
result = client.get_prompt("my-prompt")
if result.ok:
    print(result.data.name)

# Render a prompt with variables
result = client.render("my-prompt", variables={"name": "World"})
if result.ok:
    print(result.data.rendered_text)

# Create a new prompt
result = client.create_prompt(
    name="Greeting Prompt",
    slug="greeting-prompt",
    template_text="Hello, {{ name }}! You are a {{ role }}.",
    template_format="jinja2",
    tags=["greetings"],
)

# Create a new version
result = client.create_version(
    "greeting-prompt",
    template_text="Hi {{ name }}! Your role is {{ role }}.",
    change_note="Simplified greeting",
)

# Promote a version to a label
result = client.promote("greeting-prompt", version=2, label="production")
```

## CLI Scanner

The package includes a CLI tool to scan your codebase for hardcoded prompts:

```bash
# Preview what the scanner finds
apb scan ./src --team my-team --dry-run

# Import all found prompts
apb scan ./src --team my-team --auto

# Interactive import
apb scan ./src --team my-team
```

### Scanner Flags

| Flag | Description |
|---|---|
| `<path>` | Directory to scan (required) |
| `--team <slug>` | Team slug to import into (required) |
| `--dry-run` | Show findings without importing |
| `--auto` | Import all without confirmation |
| `--min-length N` | Minimum string length (default: 100) |

## API Reference

All methods return `APIResponse[T]` with fields:
- `ok: bool` — whether the request succeeded
- `status_code: int` — HTTP status code
- `data: T | None` — response data (when `ok` is True)
- `error: str | None` — error message (when `ok` is False)

### Prompts

| Method | Description |
|---|---|
| `list_prompts(tag?, search?)` | List all prompts |
| `get_prompt(slug)` | Get prompt details |
| `create_prompt(...)` | Create a new prompt |
| `update_prompt(slug, ...)` | Update prompt metadata |
| `delete_prompt(slug)` | Delete a prompt |

### Versions

| Method | Description |
|---|---|
| `list_versions(slug)` | List all versions |
| `get_version(slug, version_number)` | Get specific version |
| `create_version(slug, ...)` | Create a new version |

### Rendering

| Method | Description |
|---|---|
| `render(slug, label?, variables?)` | Render a prompt template |

### Labels

| Method | Description |
|---|---|
| `list_labels()` | List team labels |
| `create_label(name, ...)` | Create a team label |
| `delete_label(name)` | Delete a team label |
| `list_prompt_labels(slug)` | List labels for a prompt |
| `assign_label(slug, label, version)` | Assign label to version |
| `label_impact(slug)` | Analyze change impact |

### Promote / Rollback

| Method | Description |
|---|---|
| `promote(slug, version, label)` | Assign label to a version |
| `rollback(slug, label)` | Rollback label to previous version |

### Snapshots

| Method | Description |
|---|---|
| `list_snapshots()` | List snapshots |
| `create_snapshot(name, ...)` | Create a snapshot |
| `restore_snapshot(snapshot_id)` | Restore a snapshot |

### Health & Analysis

| Method | Description |
|---|---|
| `get_health(slug)` | Get prompt health score |
| `refresh_health(slug)` | Recompute health score |
| `list_analysis(limit?)` | List analysis results |
| `run_analysis()` | Run new analysis |

### System

| Method | Description |
|---|---|
| `health_check()` | Check API health |

## Using the Scanner Programmatically

```python
from aipromptbucket import Scanner

scanner = Scanner(min_length=100)
findings = scanner.scan("./src")

for finding in findings:
    print(f"{finding.file}:{finding.line} — {finding.detected_format}")
    print(f"  Variables: {finding.variables}")
```

## License

MIT — Bright Wing Solutions LLC
