prebuilt.tldr2.models¶

Models for the News Research Agent.

This module defines all Pydantic models used by the news research agent for structured outputs, API parameters, and data validation.

Examples

>>> from news_research.models import NewsApiParams, ArticleSummary
>>> params = NewsApiParams(q="AI news", sources="bbc-news")
>>> summary = ArticleSummary(title="...", summary="...", confidence=0.9)

All models use Pydantic v2 with Field descriptions for documentation

and validation. Models are designed to be serializable and type-safe.

Note

Following Haive conventions, all fields use descriptive names without underscores. Private attributes use PrivateAttr from Pydantic.

Classes¶

`ArticleContent`	Full article content with extracted text.
`ArticleMetadata`	Metadata for a news article.
`ArticleSummary`	Summarized article with key points.
`ErrorResponse`	Error response model for agent failures.
`NewsApiParams`	Parameters for NewsAPI requests.
`ResearchAnalysis`	Analysis results from collected articles.
`ResearchReport`	Final research report structure.
`SearchDecision`	Decision model for search continuation logic.

Module Contents¶

class prebuilt.tldr2.models.ArticleContent(/, **data)¶

Bases: pydantic.BaseModel

Full article content with extracted text.

Extends ArticleMetadata with the full text content extracted from web scraping.

Parameters:: data (Any)

title¶: Article headline

url¶: Full URL to the article

description¶: Brief article description

text¶: Full article text content

word_count¶: Number of words in the article

extraction_confidence¶: Confidence score for text extraction

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

calculate_word_count()¶

Calculate word count if not provided.

Return type:: ArticleContent

class prebuilt.tldr2.models.ArticleMetadata(/, **data)¶

Bases: pydantic.BaseModel

Metadata for a news article.

Represents the basic information about an article retrieved from NewsAPI before full text extraction.

Parameters:: data (Any)

title¶: Article headline

url¶: Full URL to the article

description¶: Brief article description

source¶: News source information

published_at¶: Publication timestamp

author¶: Article author (if available)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class prebuilt.tldr2.models.ArticleSummary(/, **data)¶

Bases: pydantic.BaseModel

Summarized article with key points.

Represents a fully processed article with title, URL, and bullet-point summary.

Parameters:: data (Any)

title¶: Article headline

url¶: Full URL to the article

summary¶: Bullet-point summary of key points

relevance_score¶: How relevant the article is to the query

key_topics¶: Main topics covered in the article

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class prebuilt.tldr2.models.ErrorResponse(/, **data)¶

Bases: pydantic.BaseModel

Error response model for agent failures.

Structured error information for debugging and user feedback.

Parameters:: data (Any)

error_type¶: Classification of the error

message¶: Human-readable error message

details¶: Additional error context

timestamp¶: When the error occurred

recoverable¶: Whether the operation can be retried

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class prebuilt.tldr2.models.NewsApiParams(/, **data)¶

Bases: pydantic.BaseModel

Parameters for NewsAPI requests.

This model structures the parameters needed to make NewsAPI calls, ensuring proper validation and formatting of search queries.

Parameters:: data (Any)

q¶: Search query keywords (1-3 concise terms)

sources¶: Comma-separated list of news sources

from_param¶: Start date for article search (YYYY-MM-DD format)

to¶: End date for article search (YYYY-MM-DD format)

language¶: Language code for articles (default: ‘en’)

sort_by¶: Sort order for results

page_size¶: Number of results per page

Examples

>>> params = NewsApiParams(
...     q="artificial intelligence",
...     sources="bbc-news,techcrunch",
...     from_param="2024-01-01",
...     to="2024-01-31"
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class Config¶: Pydantic configuration.

classmethod validate_from_date(v)¶

Validate from_param is a valid date string.

Parameters:: v (str)
Return type:: str

classmethod validate_to_date(v)¶

Validate to is a valid date string.

Parameters:: v (str)
Return type:: str

class prebuilt.tldr2.models.ResearchAnalysis(/, **data)¶

Bases: pydantic.BaseModel

Analysis results from collected articles.

Comprehensive analysis of all collected articles including themes, patterns, and insights.

Parameters:: data (Any)

main_themes¶: Primary themes identified across articles

key_findings¶: Most important discoveries

conflicting_info¶: Any contradictions found

confidence_level¶: Overall confidence in the analysis

data_gaps¶: Missing information or areas needing more research

trend_analysis¶: Identified trends or patterns

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class prebuilt.tldr2.models.ResearchReport(/, **data)¶

Bases: pydantic.BaseModel

Final research report structure.

Complete research report with executive summary, detailed sections, and recommendations.

Parameters:: data (Any)

title¶: Report title

executive_summary¶: High-level summary of findings

sections¶: Detailed report sections

recommendations¶: Actionable recommendations

sources_count¶: Number of sources analyzed

confidence_score¶: Overall confidence in the report

metadata¶: Additional report metadata

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

to_markdown()¶

Convert report to markdown format.

Returns:: Formatted markdown string of the report
Return type:: str

Examples

>>> report = ResearchReport(...)
>>> markdown = report.to_markdown()
>>> print(markdown)

classmethod validate_sections(v)¶

Ensure each section has required fields.

Parameters:: v (List[Dict[str, str]])
Return type:: List[Dict[str, str]]

class prebuilt.tldr2.models.SearchDecision(/, **data)¶

Bases: pydantic.BaseModel

Decision model for search continuation logic.

Used by the agent to decide whether to continue searching or proceed with analysis.

Parameters:: data (Any)

action¶: Next action to take

reason¶: Explanation for the decision

confidence¶: Confidence in the decision

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.