Metadata-Version: 2.4
Name: promptkit-claude
Version: 0.1.0
Summary: Token-efficient prompting and agentic workflows for Claude
Project-URL: Homepage, https://github.com/jasonstillchasin/claude-kit
Project-URL: Repository, https://github.com/jasonstillchasin/claude-kit
Project-URL: Issues, https://github.com/jasonstillchasin/claude-kit/issues
License: MIT
License-File: LICENSE
Keywords: ai,anthropic,caching,claude,efficiency,llm,prompt,token
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: anthropic<1.0,>=0.28
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# promptkit-claude

Token-efficient prompting and agentic workflows for Claude.

## Install

```bash
pip install promptkit-claude
```

## Quick Start — Offline (no API key needed)

```python
from claude_kit.compress import compress
from claude_kit.templates import summarize

# Remove filler phrases from any prompt (no API key needed)
prompt = compress("Please carefully analyze the following and provide a detailed summary")
# → "analyze the following and provide a summary"

# Build a token-efficient prompt
prompt = summarize(document, format="bullet", max_bullets=5)
```

## Quick Start — With API Key

```python
from claude_kit.cache import CachedClient

client = CachedClient()

# NOTE: First call warms the cache — expect 0% hit rate.
# Subsequent calls with the same system prompt hit the cache.
response = client.message(
    system="You are a helpful assistant with a long system prompt...",
    user="Hello!",
    cache_system=True,
)

print(client.cache_stats())
# → {"cache_hit_rate": "74%", "tokens_saved": 1840, "savings_usd": "$0.0023"}
```

## Session Cost Tracking

```python
from claude_kit.tracker import Tracker

with Tracker() as tracker:
    response = tracker.client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Summarize quantum computing."}],
    )

print(tracker.summary())
# → {"input_tokens": 12, "output_tokens": 340, "total_cost_usd": "$0.0014"}
```

## Agent Composition

```python
from claude_kit.agent import Chain, Retry

# Chain: pipe output of one prompt into the next
result = Chain([
    "Summarize this document: {input}",
    "Extract action items from: {input}",
]).run(input=document)

# Retry: retry on failure with exponential backoff
safe_call = Retry(max_attempts=3).wrap(client.message)
response = safe_call(user="Tell me a joke.")
```

## Async Support

```python
from claude_kit.cache import AsyncCachedClient

client = AsyncCachedClient()

async def main():
    response = await client.message(
        system="You are a concise assistant.",
        user="What is 2 + 2?",
        cache_system=True,
    )
    return response
```

## CLI

```bash
promptkit-claude compress "Please carefully explain this in detail"
# → "explain this in detail"
```

## Modules

| Module      | What it does                            | Needs API key? |
|-------------|-----------------------------------------|----------------|
| `compress`  | Removes filler phrases from prompts     | No             |
| `templates` | Token-efficient prompt templates        | No             |
| `tracker`   | Session cost tracking                   | Yes (wraps SDK)|
| `cache`     | `CachedClient` with `cache_control`     | Yes            |
| `agent`     | `Chain` / `Retry` / `Fallback` / `Parallel` | Yes        |

## Versioning

We follow semver. Patch: bug fixes. Minor: new APIs, backwards compatible. Major: breaking changes with migration notes in CHANGELOG.

## v0.2 Roadmap

- `Fallback` and `Parallel` agent primitives with full test coverage
- `cache_tools` support in `CachedClient` for tool-use payloads
- `templates.classify()` and `templates.extract()` for common extraction tasks
- Token budget warnings and hard caps via `Tracker`
- Rich CLI output with cost breakdown per call
- LangChain and LlamaIndex adapter shims
