docs: add Python, TypeScript, and cURL examples for Enso API

README.md

@@ -28,3 +28,29 @@ curl https://api.hanzo.ai/v1/chat/completions \
 
 The API speaks the OpenAI wire format, so any OpenAI SDK works with
 `base_url="https://api.hanzo.ai/v1"`.
+
+## Examples
+
+Runnable client examples in this repository:
+
+- **Python**: [`examples/python/client.py`](examples/python/client.py)
+  ```bash
+  pip install -r examples/python/requirements.txt
+  export HANZO_API_KEY="your-api-key"
+  python examples/python/client.py
+  ```
+
+- **TypeScript**: [`examples/typescript/client.ts`](examples/typescript/client.ts)
+  ```bash
+  cd examples/typescript
+  npm install
+  export HANZO_API_KEY="your-api-key"
+  npm start
+  ```
+
+- **cURL**: [`examples/curl/chat.sh`](examples/curl/chat.sh)
+  ```bash
+  export HANZO_API_KEY="your-api-key"
+  ./examples/curl/chat.sh
+  ```
+

examples/curl/chat.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Check for HANZO_API_KEY
+if [[ -z "${HANZO_API_KEY:-}" ]]; then
+  echo "Error: HANZO_API_KEY is not set" >&2
+  exit 1
+fi
+
+BASE_URL="${HANZO_BASE_URL:-https://api.hanzo.ai/v1}"
+
+echo "=== 1. Non-streaming call with enso-auto ==="
+curl -s -X POST "${BASE_URL}/chat/completions" \
+  -H "Authorization: Bearer ${HANZO_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "enso-auto",
+    "messages": [
+      {"role": "system", "content": "You are a concise decision assistant."},
+      {"role": "user", "content": "What are the core components of Hanzo Enso?"}
+    ],
+    "temperature": 0.7
+  }' | jq .
+
+echo ""
+echo "=== 2. Streaming call with enso-flash ==="
+curl -N -s -X POST "${BASE_URL}/chat/completions" \
+  -H "Authorization: Bearer ${HANZO_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "enso-flash",
+    "messages": [
+      {"role": "user", "content": "List 3 advantages of pure Rust over Python for production inference."}
+    ],
+    "stream": true
+  }'
+echo ""

examples/python/client.py

@@ -0,0 +1,51 @@
+"""Enso Python example using OpenAI SDK.
+
+Enso serves three frontier tiers:
+- enso-ultra: hardest problems, top-tier reasoning and accuracy
+- enso-pro: daily tasks, frontier quality
+- enso-flash: high volume, low latency, low cost
+- enso-auto: intelligent routing to the optimal tier
+"""
+
+import os
+from openai import OpenAI
+
+api_key = os.environ.get("HANZO_API_KEY")
+if not api_key:
+    raise ValueError("HANZO_API_KEY environment variable is required")
+
+client = OpenAI(
+    api_key=api_key,
+    base_url="https://api.hanzo.ai/v1",
+)
+
+def chat_example():
+    response = client.chat.completions.create(
+        model="enso-auto",
+        messages=[
+            {"role": "system", "content": "You are a helpful and concise assistant."},
+            {"role": "user", "content": "Explain the difference between model routing and speculative decoding."},
+        ],
+        temperature=0.7,
+    )
+    print("Response from Enso:")
+    print(response.choices[0].message.content)
+
+def streaming_example():
+    print("\nStreaming response:")
+    stream = client.chat.completions.create(
+        model="enso-flash",
+        messages=[
+            {"role": "user", "content": "Write a three-line poem about computational reasoning."},
+        ],
+        stream=True,
+    )
+    for chunk in stream:
+        content = chunk.choices[0].delta.content
+        if content:
+            print(content, end="", flush=True)
+    print()
+
+if __name__ == "__main__":
+    chat_example()
+    streaming_example()

examples/python/requirements.txt

@@ -0,0 +1,3 @@
+openai>=1.30.0
+httpx>=0.27.0
+pydantic>=2.0.0

examples/typescript/client.ts

@@ -0,0 +1,46 @@
+import OpenAI from "openai";
+
+const apiKey = process.env.HANZO_API_KEY;
+if (!apiKey) {
+  console.error("Error: HANZO_API_KEY environment variable is required");
+  process.exit(1);
+}
+
+const client = new OpenAI({
+  apiKey,
+  baseURL: "https://api.hanzo.ai/v1",
+});
+
+async function main() {
+  console.log("Calling Enso via TypeScript OpenAI client...");
+
+  // 1. Standard completion with enso-auto
+  const completion = await client.chat.completions.create({
+    model: "enso-auto",
+    messages: [
+      { role: "system", content: "You are an expert engineer." },
+      { role: "user", content: "What is masked block diffusion in decision models?" },
+    ],
+  });
+
+  console.log("\nEnso Response:");
+  console.log(completion.choices[0].message.content);
+
+  // 2. Streaming completion with enso-flash
+  console.log("\nStreaming with enso-flash:");
+  const stream = await client.chat.completions.create({
+    model: "enso-flash",
+    messages: [
+      { role: "user", content: "List 3 advantages of pure Rust runtime over Python for inference." },
+    ],
+    stream: true,
+  });
+
+  for await (const chunk of stream) {
+    const text = chunk.choices[0]?.delta?.content || "";
+    process.stdout.write(text);
+  }
+  console.log("\n");
+}
+
+main().catch(console.error);

examples/typescript/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "enso-typescript-example",
+  "version": "1.0.0",
+  "description": "Example using Enso models with OpenAI TypeScript SDK",
+  "main": "client.ts",
+  "scripts": {
+    "start": "tsx client.ts"
+  },
+  "dependencies": {
+    "openai": "^4.50.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.16.0",
+    "typescript": "^5.4.0"
+  }
+}