youdotcom-temporal

Durable You.com search, answer, research, and contents Activities for Temporal.

Exposes You.com API calls as Temporal Activities with proper error mapping, retry semantics, and workflow sandbox support. Ships as a SimplePlugin for one-line setup, or as standalone activity functions for manual worker wiring.

Installation

pip install youdotcom-temporal

Requires Python 3.10+. Uses the official youdotcom Python SDK (>=3.0.0) and temporalio (>=1.27.0).

Quickstart

Set your You.com API key (get one at you.com/platform):

export YDC_API_KEY=your-key-here

Start a local Temporal server:

temporal server start-dev

Plugin path (recommended)

from temporalio.client import Client
from temporalio.worker import Worker
from youdotcom_temporal import YouPlugin

from hello_search_workflow import HelloSearch  # see examples/

async def main():
    client = await Client.connect("localhost:7233")
    worker = Worker(
        client,
        task_queue="you-search",
        workflows=[HelloSearch],
        plugins=[YouPlugin()],
    )
    await worker.run()

The plugin auto-registers all activities and adds the SDK's runtime modules to the workflow sandbox passthrough.

Manual path

If you prefer to manage your own worker wiring:

from temporalio.worker import Worker
from youdotcom_temporal import you_activities

worker = Worker(
    client,
    task_queue="you-search",
    workflows=[HelloSearch],
    activities=you_activities(),
)

Activities

All activities return JSON-serializable dicts (via model_dump(mode="json")).

SearchInput

AnswerInput

ResearchInput

youdotcom_research_background accepts the same ResearchInput but always runs in background mode. It uses the SDK's research_and_wait_async helper to submit, stream, and poll until the task completes. For frontier effort, set timeout_s=14400 and an appropriate StartToClose timeout on the workflow side.

FinanceResearchInput

ContentsInput

Error handling

The SDK's built-in HTTP retries are disabled (retry_config=None) so Temporal is the single retry authority. Set RetryPolicy on workflow.execute_activity to control backoff and max attempts. See examples/hello_search_workflow.py for a complete example.

The default HTTP timeout is 300s (YouConfig.timeout_seconds). This covers deep/exhaustive inline research calls. Override via YouConfig(timeout_seconds=...) if needed.

Security

Never pass your API key as a workflow or activity argument. Workflow inputs are recorded in Temporal history in plaintext. The key must come from the worker environment (YDC_API_KEY) or YouConfig set on the worker side.

from youdotcom_temporal import set_config, YouConfig

set_config(YouConfig(api_key="your-key"))  # worker-side only

Examples

See the examples/ directory:

• hello_search_workflow.py - a simple search workflow with RetryPolicy
• hello_background_research_workflow.py - long-running research via youdotcom_research_background (use timeout_s=14400 and a multi-hour start_to_close_timeout for frontier effort)
• run_worker.py - starts a worker with YouPlugin
• run_workflow.py - executes the search workflow
• run_background_research_workflow.py - executes the background research workflow

# Terminal 1
temporal server start-dev

# Terminal 2
python examples/run_worker.py

# Terminal 3 (search example)
python examples/run_workflow.py

# Terminal 3 (background research example)
python examples/run_background_research_workflow.py

Development

uv sync --group dev
uv run ruff check
uv run mypy src
uv run pytest                          # unit tests (no network)
uv run pytest -m integration           # integration tests (needs YDC_API_KEY + local Temporal server)

License

MIT