Metadata-Version: 2.4
Name: localstack-claude
Version: 0.1.0
Summary: Claude (Anthropic) API emulator – LocalStack extension
Author: LocalStack Team
Project-URL: Homepage, https://github.com/localstack/localstack-extensions/tree/main/claude
Keywords: LocalStack,Anthropic,Claude,AI,emulator,testing
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8
Requires-Dist: rolo>=0.8
Requires-Dist: werkzeug>=2.3
Provides-Extra: localstack
Requires-Dist: localstack-core; extra == "localstack"
Provides-Extra: dev
Requires-Dist: anthropic>=0.40; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: requests; extra == "dev"
Requires-Dist: werkzeug; extra == "dev"
Provides-Extra: ollama
Requires-Dist: requests>=2.28; extra == "ollama"
Provides-Extra: transformers
Requires-Dist: transformers>=4.40; extra == "transformers"
Requires-Dist: torch; extra == "transformers"
Provides-Extra: snapshot
Requires-Dist: localstack-snapshot; extra == "snapshot"

# claude-local

A lightweight local emulator for the [Anthropic Claude API](https://platform.claude.com/docs/en/api/overview), built for testing and local development.

Install it as a **LocalStack extension** to intercept Claude API calls within your LocalStack-powered test environment — no API key, no network, no credits consumed.

## Quick start

### LocalStack extension

```bash
# Install into a running LocalStack instance
pip install localstack-claude
localstack extensions install localstack-claude

# Or dev mode
make ls-dev
```

Then point your SDK at:

```
ANTHROPIC_BASE_URL=http://claude.localhost.localstack.cloud:4566
ANTHROPIC_API_KEY=test-key
```

## API coverage

| Endpoint | Status |
|---|---|
| `POST /v1/messages` | ✅ |
| `POST /v1/messages` (streaming) | ✅ |
| `GET /v1/models` | ✅ |
| `GET /v1/models/{id}` | ✅ |
| `POST /v1/messages/batches` | 🔜 |

## Supported models

All current Claude models are recognized (by versioned ID or alias):

- `claude-opus-4-7` / `claude-opus-4-7-20250514`
- `claude-sonnet-4-6` / `claude-sonnet-4-6-20250514`
- `claude-haiku-4-5` / `claude-haiku-4-5-20251001`
- `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022`
- `claude-3-opus-20240229`, `claude-3-sonnet-20240229`, `claude-3-haiku-20240307`

## Response behaviour

The emulator does **not** call a real LLM. It returns a deterministic response that can be configured:

```bash
# Environment variable (set before startup)
CLAUDE_LOCAL_RESPONSE="My custom response"

# Runtime override (POST to the control plane)
curl -s -X POST http://localhost:5002/_claude/config \
  -H "Content-Type: application/json" \
  -d '{"response": "My custom response"}'
```

## Tool use

Force a tool call response by sending the `X-Claude-Local-Tool: <tool_name>` header,
or by setting `tool_choice` to `{"type": "any"}` in the request.

## Snapshot testing

`claude-local` ships with snapshot tests that record real Anthropic API responses and
verify the emulator produces structurally identical output (using
[localstack-snapshot](https://github.com/localstack/localstack-snapshot/)).

```bash
# Install deps
pip install -e ".[dev,snapshot]"

# Record real API responses
ANTHROPIC_API_KEY=sk-ant-... pytest -m snapshot --snapshot-update

# Verify emulator parity (no key needed)
pytest -m snapshot
```

## Development

```bash
make install-dev   # install with dev deps
make test          # run all tests
make run           # start emulator on port 5002
make lint          # ruff check
```

## License

Apache 2.0
