# Speakeasy SDK Generation

This guide documents the workflow for generating and regenerating the SDK with Speakeasy.

## Prerequisites

- [Speakeasy CLI](https://www.speakeasy.com/docs/speakeasy-cli/getting-started) installed
- OpenAPI specification file in `oas/dev/`

## Generation Workflow

### 1. Generate SDK with Speakeasy

```bash
speakeasy generate sdk \
  --lang python \
  --out . \
  --schema oas/dev/Specifica\ API\ -\ ANNCSU\ –\ Consultazione\ per\ le\ PA.yaml
```

### 2. Run post-generation script

After each Speakeasy generation, run the post-generation script to update the package structure:

```bash
uv run python scripts/post_speakeasy_generation.py
```

This script:
- Removes duplicated infrastructure files from API packages
- Updates imports to use shared modules in `anncsu.common.sdk`

### 3. Verify with tests

```bash
uv run pytest tests/ -q
```

## Post-Generation Script Options

```bash
# Process pa/ package (default)
uv run python scripts/post_speakeasy_generation.py

# Process a specific package
uv run python scripts/post_speakeasy_generation.py --package pa

# Process all API packages
uv run python scripts/post_speakeasy_generation.py --all

# Dry run (preview changes without applying)
uv run python scripts/post_speakeasy_generation.py --dry-run

# Show help
uv run python scripts/post_speakeasy_generation.py --help
```

## Adding a New API Package

When adding a new API package (e.g., `odonimi` for Aggiornamento odonimi):

1. Generate the package with Speakeasy using the appropriate OpenAPI spec
2. Run the post-generation script:
   ```bash
   uv run python scripts/post_speakeasy_generation.py --package odonimi
   ```
3. Add the package to the list in `scripts/post_speakeasy_generation.py` for future `--all` runs

## Important Notes

> **WARNING**: The `common/sdk/` directory contains shared infrastructure that is NOT regenerated by Speakeasy. Do not delete it during regeneration.

> **NOTE**: Always run the post-generation script after each Speakeasy regeneration to maintain the correct package structure.
