Skip to content

refactor(core): standard content blocks #32085

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 20 commits into from
Jul 22, 2025

Conversation

mdrxy
Copy link
Collaborator

@mdrxy mdrxy commented Jul 17, 2025

  • block_type replaces both old type and source_type fields
    • Encodes the full semantic of each block in one literal string
  • Benefits:
    • Unambiguous dispatch: only ever switch on block_type, instead of both type and source_type
    • Type safety: each Literal value in block_type directly maps to exactly one TypedDict.
  • Note: collapsed the ID‐based blocks into a single "file" bucket for three main reasons:
    1. An ID (e.g. a handle, storage key, cloud object ID) is by definition opaque. There's no reliable way to infer "this ID points to an image vs. an audio clip vs. a PDF." Treating every opaque ID as a generic file means you don't risk mistyping or misrouting it based on assumptions about its contents.
    2. Most provider SDKs or APIs that consume "ID" blocks simply expect a file reference (e.g. upload-by-reference, fetch-by-ID), not a media‐specific variant. By funneling all IDs through a single data:file:id channel, you simplify adapters like convert_to_openai_data_block, and avoid boilerplate branching on media kind
    3. If tomorrow we discover a storage system that uses IDs but also provides MIME metadata server-side, we can enrich the generic file block with a mime_type field or introduce a new discriminator (e.g. data:image:id). But until there's a strong, real-world need to distinguish "ID for image" vs. "ID for audio," the single file:id variant keeps the schema lean

@mdrxy mdrxy requested a review from eyurtsev as a code owner July 17, 2025 15:26
Copy link

vercel bot commented Jul 17, 2025

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Comments Updated (UTC)
langchain ✅ Ready (Inspect) Visit Preview 💬 Add feedback Jul 22, 2025 0:56am

Copy link
Collaborator

@sydney-runkle sydney-runkle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like block_type, don't think we should use it on annotations. Have some remaining questions about multimodal



def is_data_content_block(
Copy link
Collaborator

@ccurme ccurme Jul 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't mind updating the types but I don't think we should break untyped dicts in these formats in 0.4 if we can avoid it. If we decide to migrate IMO we should retain backward compatibility and emit deprecation warnings in the appropriate code paths (you may be able to just add a warning to is_data_content_block but we'll need to check integrations).

Copy link
Collaborator

@sydney-runkle sydney-runkle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice progress, some nits

"""Signature of the reasoning.

Inspired by:
- https://ai.google.dev/gemini-api/docs/thinking#signatures
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIK Gemini doesn't include signature on thinking parts, rather on text with thought=False or function calls.

@mdrxy mdrxy changed the title refactor: standard content blocks refactor(core): standard content blocks Jul 18, 2025
Copy link

codspeed-hq bot commented Jul 21, 2025

CodSpeed WallTime Performance Report

Merging #32085 will not alter performance

Comparing mdrxy/updated-content-blocks (d4a0c10) with standard_outputs (3c19caf)

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

Summary

✅ 13 untouched benchmarks

@mdrxy mdrxy requested a review from Copilot July 21, 2025 19:24
Copy link

codspeed-hq bot commented Jul 21, 2025

CodSpeed Instrumentation Performance Report

Merging #32085 will not alter performance

Comparing mdrxy/updated-content-blocks (d4a0c10) with standard_outputs (3c19caf)

Summary

✅ 14 untouched benchmarks

mime_type: Literal["text/plain"]
"""MIME type of the file. Required for base64."""

base64: str
Copy link
Preview

Copilot AI Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Required base64 field conflicts with optional text field. If text is optional when base64 is provided, then base64 should probably be NotRequired as well to allow for text-only usage.

Suggested change
base64: str
base64: NotRequired[str]

Copilot uses AI. Check for mistakes.

Comment on lines 452 to 453
base64: str
"""Data as a base64 string."""
Copy link
Preview

Copilot AI Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Required base64 field is inconsistent with the presence of optional file_id field. If content can be provided via file_id, then base64 should be NotRequired to allow for ID-only usage.

Suggested change
base64: str
"""Data as a base64 string."""
base64: NotRequired[str]
"""Data as a base64 string. Optional if `file_id` is provided."""

Copilot uses AI. Check for mistakes.

except ValidationError:
return False
else:
return True


# These would need to be refactored
def convert_to_openai_image_block(content_block: dict[str, Any]) -> dict:
"""Convert image content block to format expected by OpenAI Chat Completions API."""
if content_block["source_type"] == "url":
Copy link
Preview

Copilot AI Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This function references the old source_type field which has been removed in the refactor. This will cause a KeyError when called. The function needs to be updated to work with the new unified type system.

Copilot uses AI. Check for mistakes.


Returns:
True if the content block is a data content block, False otherwise.
"""
try:
_ = _DataContentBlockAdapter.validate_python(content_block)
_DataAdapter.validate_python(block)
except ValidationError:
return False
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we return False or block.get("type") in ("audio", "image", "video)" and "source_type" in block, I believe we keep backwards compat.

@ccurme ccurme merged commit b24f90d into standard_outputs Jul 22, 2025
53 of 66 checks passed
@ccurme ccurme deleted the mdrxy/updated-content-blocks branch July 22, 2025 13:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants