# @agentguard/sdk

TypeScript SDK for [AgentGuard](https://github.com/agentguard/agentguard) — quality-assured LLM code generation.

This is a **thin HTTP wrapper** (~500 lines). All intelligence lives in the Python engine.

## Install

```bash
npm install @agentguard/sdk
```

## Quick Start

```typescript
import { AgentGuard } from "@agentguard/sdk";

// Connect to a local AgentGuard server
const ag = new AgentGuard({ url: "http://localhost:8420" });

// Generate code from a spec
const result = await ag.generate({
  spec: "A user auth API with JWT tokens",
  archetype: "api_backend",
  llm: "anthropic/claude-sonnet-4-20250514",
});

console.log(Object.keys(result.files));
// ["src/auth/main.py", "src/auth/service.py", ...]

console.log(result.trace);
// { total_llm_calls: 12, total_cost: { total: "0.34", currency: "USD" }, ... }
```

## Validate Existing Code

```typescript
const report = await ag.validate({
  files: { "main.py": myCode },
  archetype: "api_backend",
});

if (!report.passed) {
  for (const err of report.errors) {
    console.error(`${err.file_path}:${err.line}: ${err.message}`);
  }
}
```

## Self-Challenge

```typescript
const result = await ag.challenge({
  code: myCode,
  criteria: ["No hardcoded secrets", "All endpoints have error handling"],
});

console.log(result.passed ? "✓ Passed" : "✗ Failed");
```

## Stream Progress (SSE)

```typescript
for await (const event of ag.generateStream({ spec: "...", archetype: "api_backend" })) {
  if (event.event === "level_complete") {
    console.log(`Level ${event.level}: ${event.files.length} files`);
  } else if (event.event === "complete") {
    console.log(`Done! ${Object.keys(event.files).length} files generated`);
  }
}
```

## Configuration

```typescript
const ag = new AgentGuard({
  url: "http://localhost:8420",      // Default
  apiKey: "ag_xxx",                  // Optional — required for cloud
  timeout: 300_000,                  // 5 min default
});
```

## API

| Method | Description |
|--------|-------------|
| `generate(req)` | Full top-down generation pipeline |
| `generateStream(req)` | Stream generation progress via SSE |
| `validate(req)` | Structural validation (syntax, lint, types, imports) |
| `challenge(req)` | LLM self-challenge against quality criteria |
| `skeleton(req)` | L1 only: file tree |
| `contracts(req)` | L2: typed stubs |
| `wiring(req)` | L3: import graph |
| `logic(req)` | L4: function bodies |
| `listArchetypes()` | List available archetypes |
| `getArchetype(id)` | Get archetype details |
| `listTraces()` | List recent traces |
| `getTrace(id)` | Get trace details |
| `health()` | Health check |

## License

MIT
