Skip to content

MIGRATION.md

Latest commit

 

History

History
332 lines (269 loc) · 8.18 KB

MIGRATION.md

File metadata and controls

332 lines (269 loc) · 8.18 KB

Migration Guide

1.x → 2.3.0 (Latest)

This guide covers breaking changes introduced in 2.3.0. If you are upgrading from 1.x, also read the 1.x → 2.0 section below.

Breaking Changes in 2.3.0

Python 3.10 now required

The minimum supported Python version has been raised from >=3.9.2 to >=3.10. If you are running Python 3.9, you must upgrade before installing this version.

python --version   # must be 3.10 or later
pip install "youdotcom>=2.3.0"

Search API: count default changed

you.search.unified() now defaults count to 10 (previously None/no default). If your code omits count and relies on the API-server default, you will now always receive 10 results.

# Before (2.x < 2.3.0): count was unset, server decided
res = you.search.unified(query="AI news")

# After (2.3.0+): equivalent explicit call
res = you.search.unified(query="AI news", count=10)

Contents API: crawl_timeout type changed

crawl_timeout has changed from float to int. Passing a float (e.g., crawl_timeout=5.5) will now raise a validation error.

# Before: float was accepted
res = you.contents.generate(urls=["https://example.com"], crawl_timeout=5.5)

# After: use int
res = you.contents.generate(urls=["https://example.com"], crawl_timeout=5)

1.x to 2.0

This guide helps you upgrade your code from You.com Python SDK 1.x to 2.0.

Quick Reference

Change Find Replace With
Import path from youdotcom.types.typesafe_models import from youdotcom.models import
Express agent agent=AgentType.EXPRESS request=ExpressAgentRunsRequest(...)
Advanced agent agent=AgentType.ADVANCED request=AdvancedAgentRunsRequest(...)
Custom agent agent="uuid-string" request=CustomAgentRunsRequest(agent="uuid-string", ...)
Verbosity enum Verbosity ReportVerbosity
Format enum Format ContentsFormats
Contents format param format_=Format.X formats=[ContentsFormats.X]

Step-by-Step Migration

Step 1: Update Imports

Before:

from youdotcom import You
from youdotcom.types.typesafe_models import (
    AgentType,
    SearchEffort,
    Verbosity,
    Country,
    Freshness,
    LiveCrawl,
    Format,
    get_text_tokens,
    stream_text_tokens,
)

After:

from youdotcom import You
from youdotcom.models import (
    ExpressAgentRunsRequest,
    AdvancedAgentRunsRequest,
    CustomAgentRunsRequest,
    SearchEffort,
    ReportVerbosity,
    Country,
    Freshness,
    LiveCrawl,
    ContentsFormats,  # Note: Now plural (formats array)
    AgentRunsBatchResponse,
    # For streaming:
    ResponseCreated,
    ResponseStarting,
    ResponseOutputTextDelta,
    ResponseOutputContentFull,
    ResponseDone,
)

Step 2: Update Agent Calls

Express Agent

Before:

res = you.agents.runs.create(
    agent=AgentType.EXPRESS,
    input="What is the capital of France?",
    stream=False,
)

After:

res = you.agents.runs.create(
    request=ExpressAgentRunsRequest(
        input="What is the capital of France?",
        stream=False,
    )
)

Advanced Agent

Before:

res = you.agents.runs.create(
    agent=AgentType.ADVANCED,
    input="Research quantum computing",
    stream=False,
    tools=[
        ResearchTool(
            search_effort=SearchEffort.AUTO,
            report_verbosity=Verbosity.HIGH
        )
    ]
)

After:

res = you.agents.runs.create(
    request=AdvancedAgentRunsRequest(
        input="Research quantum computing",
        stream=False,
        tools=[
            ResearchTool(
                search_effort=SearchEffort.AUTO,
                report_verbosity=ReportVerbosity.HIGH  # Note: Verbosity → ReportVerbosity
            )
        ]
    )
)

Custom Agent

Before:

res = you.agents.runs.create(
    agent="your-custom-agent-uuid",
    input="Custom query",
    stream=False,
)

After:

res = you.agents.runs.create(
    request=CustomAgentRunsRequest(
        agent="your-custom-agent-uuid",
        input="Custom query",
        stream=False,
    )
)

Step 3: Update Response Handling

Batch (Non-Streaming) Responses

Before:

res = you.agents.runs.create(agent=AgentType.EXPRESS, input="...", stream=False)
get_text_tokens(res)

After:

res = you.agents.runs.create(
    request=ExpressAgentRunsRequest(input="...", stream=False)
)

if isinstance(res, AgentRunsBatchResponse):
    if res.output:
        for output in res.output:
            if output.text:
                print(output.text)

Streaming Responses

Before:

res = you.agents.runs.create(agent=AgentType.EXPRESS, input="...", stream=True)
stream_text_tokens(res)

After:

res = you.agents.runs.create(
    request=ExpressAgentRunsRequest(input="...", stream=True)
)

with res as stream:
    for chunk in stream:
        event = chunk.data
        
        if isinstance(event, ResponseOutputTextDelta):
            print(event.response.delta, end="", flush=True)
        
        elif isinstance(event, ResponseDone):
            print(f"\nDone in {event.response.run_time_ms}ms")

Step 4: Update Contents API

The Contents API has significant changes in 2.0.0:

  • format_ parameter is replaced by formats (an array)
  • New metadata format option returns json+ld and OpenGraph information
  • New crawl_timeout parameter (1-60 seconds) for controlling crawl duration

Before (1.x):

from youdotcom.types.typesafe_models import Format, print_contents

res = you.contents.generate(
    urls=["https://example.com"],
    format_=Format.MARKDOWN,
)
print_contents(res)

After (2.0):

from youdotcom.models import ContentsFormats

# Single format
res = you.contents.generate(
    urls=["https://example.com"],
    formats=[ContentsFormats.MARKDOWN],
)

# Multiple formats at once (new in 2.0.0)
res = you.contents.generate(
    urls=["https://example.com"],
    formats=[ContentsFormats.HTML, ContentsFormats.MARKDOWN, ContentsFormats.METADATA],
    crawl_timeout=30,  # Optional: 1-60 seconds
)

# Access metadata (json+ld, OpenGraph info)
for item in res:
    print(f"URL: {item.url}")
    print(f"Title: {item.title}")
    if item.metadata:
        print(f"Site Name: {item.metadata.site_name}")
        print(f"Favicon: {item.metadata.favicon_url}")

Step 5: Update Error Handling

Before:

from youdotcom.errors import (
    PostV1AgentsRunsUnauthorizedError,
    GetV1SearchUnauthorizedError,
)

After:

from youdotcom.errors import (
    AgentRuns401ResponseError,
    SearchUnauthorizedError,
)

Search and Contents APIs

The Search API remains largely unchanged. The Contents API has significant changes:

  1. Import path: Use from youdotcom.models import instead of typesafe_models
  2. Format parameter: Changed from format_ (single value) to formats (array)
  3. Format enum: Use ContentsFormats instead of Format (note the 's')
  4. New metadata format: Request ContentsFormats.METADATA to get json+ld and OpenGraph info
  5. New crawl_timeout: Optional parameter (1-60 seconds) to control crawl duration
# Search API (unchanged usage)
res = you.search.unified(
    query="AI developments",
    count=10,
    freshness=Freshness.WEEK,
    country=Country.US,
)

# Contents API (updated to use formats array)
res = you.contents.generate(
    urls=["https://example.com"],
    formats=[ContentsFormats.MARKDOWN],  # Was: format_=Format.MARKDOWN
)

# Contents API with multiple formats and metadata (new in 2.0.0)
res = you.contents.generate(
    urls=["https://example.com"],
    formats=[ContentsFormats.HTML, ContentsFormats.METADATA],
    crawl_timeout=30,  # Optional: 1-60 seconds
)
# Access metadata
if res[0].metadata:
    print(res[0].metadata.site_name)
    print(res[0].metadata.favicon_url)

Need Help?

  • See the CHANGELOG.md for complete details on all changes
  • Check the examples/ folder for working code samples
  • Open an issue on GitHub if you encounter problems