> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Generate native, type-safe client SDKs in Go, Python, and TypeScript from your contract definitions

Mizu Contract includes built-in SDK generators that create native, fully-typed client libraries from your contract definitions. Generate idiomatic code for each language with resource-based API access and first-class streaming support.

## What is SDK Generation?

SDK generation creates client libraries from your API contract. Instead of writing HTTP client code by hand for each language, you define your API once and generate clients automatically.

```
Contract Definition (api.yaml)
           │
           ▼
    ┌──────────────────┐
    │ mizu contract gen│
    │   (Go/Py/TS)     │
    └──────────────────┘
           │
           ▼
  Native Client Library
  (Types + Client + Streaming)
```

## Quick Start

Generate SDK clients using the CLI:

```bash theme={null}
# Generate a Go SDK client
mizu contract gen api.yaml --client --lang go --output ./sdk/go

# Generate a Python SDK client
mizu contract gen api.yaml --client --lang python --output ./sdk/python

# Generate a TypeScript SDK client
mizu contract gen api.yaml --client --lang typescript --output ./sdk/typescript

# Generate all languages at once
mizu contract gen api.yaml --client --lang all --output ./sdk
```

## Why Use Native SDK Generators?

### Benefits Over Manual Client Code

| Aspect           | Manual Code              | Generated SDK         |
| ---------------- | ------------------------ | --------------------- |
| **Type Safety**  | Error-prone, manual sync | Always matches server |
| **Maintenance**  | Update everywhere        | Regenerate once       |
| **Consistency**  | Varies by author         | Uniform patterns      |
| **Time to Ship** | Hours per language       | Seconds               |

### Benefits Over Generic OpenAPI-Based Generation

| Feature          | Generic Generators | Mizu SDK Generators      |
| ---------------- | ------------------ | ------------------------ |
| **Code Style**   | Generic, verbose   | Idiomatic, minimal       |
| **Dependencies** | Often many         | Minimal (stdlib-focused) |
| **API Feel**     | HTTP-centric       | Resource-oriented        |
| **Streaming**    | Limited support    | First-class SSE          |
| **Size**         | Large output       | Compact, focused         |

<Info>
  **When to use OpenAPI generators?** OpenAPI generators support 40+ languages and have mature tooling. Use them when you need languages Mizu doesn't support natively, or when you need OpenAPI compatibility with other tools. See [Client Generation](/contract/client-generation) for OpenAPI approaches.
</Info>

## Available SDK Generators

Mizu provides native SDK generators for three languages:

<CardGroup cols={3}>
  <Card title="Go" icon="golang" href="/contract/sdk-go">
    Zero dependencies, stdlib only. Fluent resource-based API with EventStream for streaming.
  </Card>

  <Card title="Python" icon="python" href="/contract/sdk-python">
    Modern Python with type hints. Sync and async clients using httpx.
  </Card>

  <Card title="TypeScript" icon="js" href="/contract/sdk-typescript">
    Runtime agnostic (Node/Bun/Deno). AsyncIterable streaming with full type inference.
  </Card>
</CardGroup>

## Quick Comparison

| Feature          | Go SDK            | Python SDK             | TypeScript SDK     |
| ---------------- | ----------------- | ---------------------- | ------------------ |
| **Output**       | Single `.go` file | uv/pip project         | npm package        |
| **HTTP Client**  | `net/http`        | `httpx`                | native `fetch`     |
| **Streaming**    | `EventStream[T]`  | Iterator/AsyncIterator | `AsyncIterable<T>` |
| **Dependencies** | None (stdlib)     | httpx                  | None               |
| **Runtimes**     | Go 1.18+          | Python 3.8+            | Node 18+/Bun/Deno  |

## How It Works

### Step 1: Define Your Contract

Create a contract definition in YAML:

```yaml theme={null}
# api.yaml
name: TodoAPI
description: Todo list API

defaults:
  base_url: http://localhost:8080

resources:
  - name: todos
    description: Manage todo items
    methods:
      - name: create
        description: Create a new todo
        input: CreateTodoInput
        output: Todo
        http:
          method: POST
          path: /todos
      - name: list
        description: List all todos
        output: TodoList
        http:
          method: GET
          path: /todos
      - name: get
        description: Get a todo by ID
        input: GetTodoInput
        output: Todo
        http:
          method: GET
          path: /todos/{id}
      - name: delete
        description: Delete a todo
        input: DeleteTodoInput
        http:
          method: DELETE
          path: /todos/{id}

types:
  - name: Todo
    kind: struct
    fields:
      - name: id
        type: string
      - name: title
        type: string
      - name: done
        type: bool
      - name: created_at
        type: time.Time
        optional: true
  - name: TodoList
    kind: slice
    elem: Todo
  - name: CreateTodoInput
    kind: struct
    fields:
      - name: title
        type: string
  - name: GetTodoInput
    kind: struct
    fields:
      - name: id
        type: string
  - name: DeleteTodoInput
    kind: struct
    fields:
      - name: id
        type: string
```

### Step 2: Generate SDK Clients

```bash theme={null}
# Generate Go SDK
mizu contract gen api.yaml --client --lang go --output ./sdk/go --package todoclient

# Generate Python SDK
mizu contract gen api.yaml --client --lang python --output ./sdk/python --package todoclient --version 1.0.0

# Generate TypeScript SDK
mizu contract gen api.yaml --client --lang typescript --output ./sdk/typescript --package todoclient --version 1.0.0
```

### Step 3: Use the Generated Clients

<CodeGroup>
  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "todoclient"
  )

  func main() {
      client := todoclient.NewClient("http://localhost:8080")
      ctx := context.Background()

      todo, err := client.Todos.Create(ctx, &todoclient.CreateTodoInput{
          Title: "Learn Mizu SDKs",
      })
      if err != nil {
          panic(err)
      }
      fmt.Printf("Created: %s\n", todo.ID)
  }
  ```

  ```python Python theme={null}
  from todoclient import Client

  client = Client(base_url="http://localhost:8080")

  todo = client.todos.create(title="Learn Mizu SDKs")
  print(f"Created: {todo.id}")
  ```

  ```typescript TypeScript theme={null}
  import { Client } from 'todoclient';

  const client = new Client({ baseURL: 'http://localhost:8080' });

  const todo = await client.todos.create({ title: 'Learn Mizu SDKs' });
  console.log(`Created: ${todo.id}`);
  ```
</CodeGroup>

## CLI Reference

### Command Syntax

```bash theme={null}
mizu contract gen <file> [flags]
```

### Flags

| Flag        | Short | Description                                                                | Default                   |
| ----------- | ----- | -------------------------------------------------------------------------- | ------------------------- |
| `--lang`    |       | Target language: `go`, `golang`, `python`, `py`, `typescript`, `ts`, `all` | `typescript`              |
| `--output`  | `-o`  | Output directory                                                           | Same as input file        |
| `--package` |       | Package/module name                                                        | Derived from service name |
| `--version` |       | Package version (Python/TypeScript)                                        | `0.0.0`                   |
| `--client`  | `-c`  | Generate full SDK client (not just types)                                  | `false`                   |

### Examples

```bash theme={null}
# Types only (lightweight, no HTTP client)
mizu contract gen api.yaml --lang go --package api

# Full SDK client for Go
mizu contract gen api.yaml --client --lang go --output ./sdk/go

# Full SDK client for Python with version
mizu contract gen api.yaml --client --lang python --output ./sdk/python --version 1.0.0

# Full SDK client for TypeScript
mizu contract gen api.yaml --client --lang typescript --output ./sdk/typescript

# All languages at once
mizu contract gen api.yaml --client --lang all --output ./sdk
```

## Choosing the Right Approach

Use this decision matrix to choose between SDK generation and OpenAPI:

| If you need...                     | Use                                                  |
| ---------------------------------- | ---------------------------------------------------- |
| Go, Python, or TypeScript client   | **Native SDK generators**                            |
| Maximum type safety                | **Native SDK generators**                            |
| Minimal dependencies               | **Native SDK generators**                            |
| Streaming (SSE) support            | **Native SDK generators**                            |
| Other languages (Java, Ruby, etc.) | OpenAPI generators                                   |
| OpenAPI ecosystem compatibility    | OpenAPI generators                                   |
| Both approaches                    | Both! Generate native SDKs and serve `/openapi.json` |

## CI/CD Integration

Regenerate SDKs on contract changes:

```yaml theme={null}
# .github/workflows/sdk.yml
name: Generate SDKs

on:
  push:
    paths:
      - 'api.yaml'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Mizu CLI
        run: go install github.com/go-mizu/mizu/cmd/cli@latest

      - name: Generate SDKs
        run: |
          mizu contract gen api.yaml --client --lang go --output ./sdk/go
          mizu contract gen api.yaml --client --lang python --output ./sdk/python
          mizu contract gen api.yaml --client --lang typescript --output ./sdk/typescript

      - name: Commit SDKs
        run: |
          git add sdk/
          git commit -m "chore: regenerate SDKs" || true
          git push
```

## What's Next?

<CardGroup cols={2}>
  <Card title="Go" icon="golang" href="/contract/sdk-go">
    Complete guide to generating and using Go SDKs
  </Card>

  <Card title="Python" icon="python" href="/contract/sdk-python">
    Complete guide to generating and using Python SDKs
  </Card>

  <Card title="TypeScript" icon="js" href="/contract/sdk-typescript">
    Complete guide to generating and using TypeScript SDKs
  </Card>

  <Card title="OpenAPI Generation" icon="file-code" href="/contract/openapi">
    Alternative approach using OpenAPI specification
  </Card>
</CardGroup>

## See Also

* [Service Definition](/contract/service) - How to define your API interface
* [Types](/contract/types) - Type system and mappings
* [Client Generation](/contract/client-generation) - OpenAPI-based approach
* [REST Transport](/contract/rest) - Exposing your service as REST API