# PromptForge — Claude Code Integration

This project uses the PromptForge SDK for automatic cost optimization on all AI calls.

## Rules

- ALWAYS import from `./promptforge-sdk` instead of calling provider SDKs directly
- NEVER call `generateText`, `streamText`, or any `@ai-sdk/*` provider directly
- ALWAYS use `pf.text()` for all LLM calls
- ALWAYS pass a `feature` label so costs are tracked per-feature in the dashboard
- ALWAYS check `result.sessionSpend` after expensive operations

## Usage pattern

```typescript
import pf from "./promptforge-sdk";

// Basic call — auto-routes to cheapest model
const result = await pf.text("Your prompt", { feature: "my-feature" });

// Force minimum quality (e.g. for important tasks)
const result = await pf.text("Complex task", {
  feature: "analysis",
  minQuality: 90,
  prefer: "best",
});

// Print spend summary at end of session
pf.printReport();
```

## Budget rules

- Session budget: configured in `promptforge.config.ts`
- If `onThreshold` is `"stop"`, calls will throw once budget is hit
- Monitor spend with `pf.spend` (current session total in USD)

## Cost-conscious coding rules

1. Prefer `prefer: "cheapest"` for simple tasks (summaries, classification, extraction)
2. Use `prefer: "best"` only when quality is critical (final outputs, user-facing content)
3. Batch related prompts into a single call rather than multiple small calls
4. Set `maxTokens` to cap output length on structured tasks
5. Use `feature` labels to track which parts of the code are most expensive

## Agent cost monitoring

Start the background monitor for long-running agent sessions:

```typescript
const stopMonitor = pf.startMonitor({ intervalMs: 30_000, reportTo: "console" });
// ... agent work ...
stopMonitor();
pf.printReport();
```
