News Tools

The news tools give you full control over Soria’s news intelligence system. Use them to trigger the processing pipeline, manage configuration branches, and browse the events and articles that the pipeline produces.

`news_pipeline`

Run the news processing pipeline or check the status of the most recent run. The pipeline fetches articles, extracts structured data, and clusters stories into events.

Parameters

string

required

The operation to perform. Accepted values:

"run" — trigger the pipeline
"status" — return the status of the latest run

string

The configuration branch to run against. Defaults to the production branch.

string[]

Specific pipeline steps to run. Omit to run all steps in sequence. Accepted values: "fetch", "extract", "stories".

string

Start date for article fetching, in YYYY-MM-DD format. Overrides the branch’s days_back setting. Use for backfills.

string

End date for article fetching, in YYYY-MM-DD format. Defaults to today.

Returns

action="run" returns:

run_id — identifier for this pipeline run
status — current run status
articles_fetched — number of articles fetched
articles_scored — number of articles scored
events_created — number of story events created

action="status" returns the same fields for the latest run, plus trigger_type and any error message if the run failed.

Examples

# Run the full pipeline on the production branch
news_pipeline(action="run")

# Run only the fetch step on a specific branch
news_pipeline(
    action="run",
    branch_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    steps=["fetch"],
)

# Backfill a date range
news_pipeline(
    action="run",
    date_from="2024-01-01",
    date_to="2024-01-31",
)

# Check pipeline status
news_pipeline(action="status")

`news_branches`

Create and manage configuration branches. Each branch holds its own fetch configuration, extraction prompt, and scheduling settings. The production branch is the default used by the pipeline and news events tools.

Parameters

string

required

The operation to perform. Accepted values: "list", "get", "create", "update", "delete", "clone".

string

The branch UUID. Required for get, update, delete, and clone.

string

Branch display name. Required for create and clone. Optional for update.

object

Branch configuration fields. Accepted keys include:

fetch_config — data source and fetching settings
extraction_prompt — prompt used during the extract step
schedule_enabled — whether the branch runs on a schedule
days_back — how many days of articles to fetch by default

Examples

# List all branches
news_branches(action="list")

# Inspect a specific branch
news_branches(
    action="get",
    branch_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
)

# Create a new branch
news_branches(
    action="create",
    name="payer-m-and-a-experiment",
    config={"days_back": 14, "schedule_enabled": False},
)

# Clone the production branch to experiment with a new extraction prompt
news_branches(
    action="clone",
    branch_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    name="extraction-prompt-v2",
)

# Update a branch's extraction prompt
news_branches(
    action="update",
    branch_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    config={"extraction_prompt": "Focus on payer M&A activity and network changes."},
)

# Delete a branch
news_branches(
    action="delete",
    branch_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
)

`news_events`

List and filter news events (clustered stories) produced by the pipeline.

Parameters

string

required

The operation to perform. Accepted values: "list", "search".

string

The configuration branch to pull events from. Defaults to the production branch.

string

Filter events by review status. Accepted values: "pending", "approved", "rejected".

number

Maximum number of events to return.

Returns

Each event includes:

label — event headline or label
article_count — number of articles contributing to this event
id — event identifier
summary — a short preview of the event summary

Examples

# List all production events
news_events(action="list")

# List pending events awaiting review
news_events(action="list", status="pending", limit=25)

# List approved events on a specific branch
news_events(
    action="list",
    branch_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    status="approved",
)

`news_articles`

List and filter individual articles processed by the pipeline. Articles are scored and assigned to buckets during the extract step.

Parameters

string

required

The operation to perform. Accepted values: "list", "search".

string

The configuration branch to pull articles from. Defaults to the production branch.

string

Filter by the article’s relevance bucket. Accepted values: "relevant", "discard".

number

Maximum number of articles to return.

Returns

Each article includes:

relevance_score — numeric score assigned during extraction
bucket — relevant, discard, or unscored
title — article headline (truncated to 80 characters)
id — article identifier
source — source name, domain, or unknown
url — direct link to the article

Examples

# List all articles on the production branch
news_articles(action="list")

# List only relevant articles, up to 50
news_articles(action="list", bucket="relevant", limit=50)

# Inspect discarded articles on a branch to tune the extraction prompt
news_articles(
    action="list",
    branch_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    bucket="discard",
    limit=20,
)

Overview

Ingestion Tools

Pipeline Tools

Warehouse & Models

Intelligence Tools

`news_pipeline`

Parameters

Returns

Examples

`news_branches`

Parameters

Examples

`news_events`

Parameters

Returns

Examples

`news_articles`

Parameters

Returns

Examples

​news_pipeline

​Parameters

​Returns

​Examples

​news_branches

​Parameters

​Examples

​news_events

​Parameters

​Returns

​Examples

​news_articles

​Parameters

​Returns

​Examples

`news_pipeline`

Parameters

Returns

Examples

`news_branches`

Parameters

Examples

`news_events`

Parameters

Returns

Examples

`news_articles`

Parameters

Returns

Examples