API fundamentals

You're Claude Code, working in my repository.

Task
Build a small Meta Model API starter module for this project covering the API fundamentals recipes: a client, a chat helper with a developer message, a streaming helper that guards empty chunks and returns the final chunk's usage, a structured-output helper with response_format json_schema, and a retry wrapper for 429, 5xx and timeouts. Add one runnable example per helper.

Read this first
Meta's docs page "API fundamentals" as Markdown: https://dev.meta.ai/docs/cookbook/api-fundamentals.md
It's the source of truth for request and response shapes. The same page for people: https://dev.meta.ai/docs/cookbook/api-fundamentals

Setup
- Base URL: https://api.meta.ai/v1
- Auth: send Authorization: Bearer $MODEL_API_KEY, reading MODEL_API_KEY from the environment. Never hard-code, print or commit the key.
- Model: muse-spark-1.3-contributor (Contributor mode: Meta may use what you send to train future models; drop -contributor for Standard mode)
- Python: the OpenAI SDK (pip install openai) with base_url="https://api.meta.ai/v1" and api_key=os.environ["MODEL_API_KEY"] works, or plain requests.

Facts to get right
- muse-spark-1.3-contributor is a reasoning model: stop, n > 1, logit_bias and verbosity return HTTP 400, and reasoning tokens bill as output.
- Chat Completions is stateless: resend the history every call. Prefer the developer role to system.
- Streaming: stream_options include_usage puts usage on the final chunk, whose delta.content is None.
- Structured output: response_format json_schema on Chat, text.format on Responses. Recursive $ref schemas are rejected.
- Retry 429, 5xx and timeouts with 0.5 * 2**attempt + uniform(0, 0.5) s waits; never retry another 4xx.
- Web search and previous_response_id are Responses API features (POST /v1/responses).

Starter code (Python)
import os
import random
import time

from openai import APIConnectionError, APIStatusError, OpenAI

client = OpenAI(base_url="https://api.meta.ai/v1", api_key=os.environ["MODEL_API_KEY"])


def complete(messages, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(model="muse-spark-1.3-contributor", messages=messages, **kwargs)
        except (APIStatusError, APIConnectionError) as exc:
            status = getattr(exc, "status_code", 500)  # a timeout has none: retry it
            if (status < 500 and status != 429) or attempt == max_retries - 1:
                raise  # any other 4xx: fix the request
        time.sleep(0.5 * 2**attempt + random.uniform(0, 0.5))


reply = complete([
    {"role": "developer", "content": "Answer in one sentence."},
    {"role": "user", "content": "What is a context window?"},
])
print(reply.choices[0].message.content, reply.usage)

Done when
- Each example runs and prints its result.
- A request with n=2 raises a 400 once, with no retries.
- The key comes from MODEL_API_KEY and never appears in code, logs or commits.
- API errors (4xx, 429) surface their message instead of failing silently.