Add OpenRouter samples: prompt batch and budget gate

[DABH]

Adds an openrouter sample with two scenarios, plus OpenRouter as a model provider for the OpenAI Agents SDK sample.

prompt_batch fans one Activity out per prompt with OpenRouter's Auto Router and returns answer, model, and reported cost per prompt. The Activity uses the openai client pointed at OpenRouter with max_retries=0, classifies 4xx as non-retryable and 408/429/5xx as retryable, passes Retry-After through as next_retry_delay, heartbeats, and sends X-OpenRouter-Cache: true so a retried identical request is served from OpenRouter's cache at $0. A --fail-once flag demonstrates that.

budget_gate is the same batch, but it pauses on a soft budget or on OpenRouter's 402 and resumes on a raise_budget Update, with a spend_report Query.

Tests use httpx.MockTransport and a fake Activity; no API key needed. Verified live against OpenRouter, including a cache hit at $0 on retry.

Docs page: temporalio/documentation#5307. TypeScript port: temporalio/samples-typescript#520.

[patbeqo]

Should we default to openrouter/auto since the README says and picks providers and models per request ?

[Copilot]

🟡 Changes recommended

Input deadlocks, serialized approval timeouts, duplicate-prompt state loss, and incomplete cost accounting need resolution.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds OpenRouter integrations for durable prompt batching, budget-aware execution, and the OpenAI Agents SDK.

Changes:

• Adds prompt-batch and budget-gate workflows with retries, caching, and cost reporting.
• Adds mocked integration tests and dependency configuration.
• Adds an OpenRouter-backed Agents SDK example and documentation.

File summaries

File	Description
uv.lock	Locks OpenRouter dependencies.
pyproject.toml	Adds the OpenRouter dependency group.
README.md	Registers the new sample.
openrouter/__init__.py	Initializes the package.
openrouter/shared.py	Defines shared inputs, results, and constants.
openrouter/activities.py	Implements OpenRouter requests and error handling.
openrouter/README.md	Documents the integration.
openrouter/prompt_batch/__init__.py	Initializes the prompt-batch package.
openrouter/prompt_batch/workflow.py	Implements concurrent prompt processing.
openrouter/prompt_batch/run_worker.py	Runs the prompt-batch worker.
openrouter/prompt_batch/run_workflow.py	Starts prompt-batch workflows.
openrouter/prompt_batch/README.md	Documents prompt batching.
openrouter/budget_gate/__init__.py	Initializes the budget-gate package.
openrouter/budget_gate/workflow.py	Implements budget reservations and pauses.
openrouter/budget_gate/run_worker.py	Runs the budget-gate worker.
openrouter/budget_gate/run_workflow.py	Starts budget-gate workflows.
openrouter/budget_gate/raise_budget.py	Sends budget updates.
openrouter/budget_gate/README.md	Documents budget controls.
tests/openrouter/__init__.py	Initializes the test package.
tests/openrouter/activity_test.py	Tests HTTP handling and caching.
tests/openrouter/prompt_batch_test.py	Tests batch result collection.
tests/openrouter/budget_gate_test.py	Tests pauses, updates, and timeouts.
openai_agents/model_providers/workflows/openrouter_workflow.py	Adds an OpenRouter agent workflow.
openai_agents/model_providers/run_openrouter_workflow.py	Starts the agent workflow.
openai_agents/model_providers/run_openrouter_worker.py	Configures the OpenRouter provider.
openai_agents/model_providers/README.md	Documents the provider example.

Review details

Suppressed comments (1)

openrouter/activities.py:192

• This simulated successful first call is billed, but its result and cost are discarded when the Activity raises. The cached retry then reports $0, so BatchResult.total_cost_usd and the budget ledger say zero even though the account was charged; the same gap occurs during the real post-response Worker crash being demonstrated. Persist/reconcile the first generation's charge externally, or clearly expose these totals as lower bounds and document that limitation for the budget gate.

        if request.fail_once_after_call and activity.info().attempt == 1:
            # Demo hook: the Worker "crashes" after the response arrived. The
            # retry re-sends the identical request and gets a cache hit.
            raise ApplicationError(
                "Simulated failure after the response was received",
                type="SimulatedFailure",
            )

• Files reviewed: 21/26 changed files
• Comments generated: 5
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.