27a6cd31a3
## Before
### Tool: ``GoogleNews.SearchNewsStories``
```python
@tool(requires_secrets=["SERP_API_KEY"])
async def search_news_stories(
context: ToolContext,
keywords: Annotated[
str,
"Keywords to search for news articles. E.g. 'Apple launches new iPhone'.",
],
country_code: Annotated[
CountryCode | None,
"2-character country code to search for news articles. "
"E.g. 'us' (United States). "
f"Defaults to '{DEFAULT_GOOGLE_NEWS_COUNTRY}'.",
] = None,
language_code: Annotated[
LanguageCode,
"2-character language code to search for news articles. E.g. 'en' (English). "
f"Defaults to '{DEFAULT_GOOGLE_NEWS_LANGUAGE}'.",
] = DEFAULT_GOOGLE_NEWS_LANGUAGE,
limit: Annotated[
int | None,
"Maximum number of news articles to return. Defaults to None "
"(returns all results found by the API).",
] = None,
) -> Annotated[dict[str, Any]]:
"""Search for news articles related to a given query."""
...
```
### Tool Definition: ``GoogleNews.SearchNewsStories``
```
{
"name": "SearchNewsStories",
"fully_qualified_name": "GoogleNews.SearchNewsStories",
"description": "Search for news articles related to a given query.",
"toolkit": {
"name": "GoogleNews",
"description": "Arcade.dev LLM tools for getting new via Google News",
"version": "2.0.0"
},
"input": {
"parameters": [
{
"name": "keywords",
"required": true,
"description": "Keywords to search for news articles. E.g. 'Apple launches new iPhone'.",
"value_schema": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
},
"inferrable": true
},
{
"name": "country_code",
"required": false,
"description": "2-character country code to search for news articles. E.g. 'us' (United States). Defaults to 'None'.",
"value_schema": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
},
"inferrable": true
},
{
"name": "language_code",
"required": false,
"description": "2-character language code to search for news articles. E.g. 'en' (English). Defaults to 'en'.",
"value_schema": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
},
"inferrable": true
},
{
"name": "limit",
"required": false,
"description": "Maximum number of news articles to return. Defaults to None (returns all results found by the API).",
"value_schema": {
"val_type": "integer",
"inner_val_type": null,
"enum": null,
},
"inferrable": true
}
]
},
"output": {
"description": "News search results with article details.",
"available_modes": [
"value",
"error"
],
"value_schema": {
"val_type": "json"
}
},
"requirements": {
"authorization": null,
"secrets": [
{
"key": "serp_api_key"
}
],
"metadata": null
},
"deprecation_message": null
},
```
## After
### Enhanced Tool: ``GoogleNews.SearchNewsStories``
```python
"""Type definitions for Google News API responses and parameters."""
from typing_extensions import TypedDict
CountryCode = str
LanguageCode = str
class SearchNewsParams(TypedDict):
"""Input parameters for searching news articles."""
keywords: str
"""Search query terms to find relevant news articles \
(e.g., 'Apple launches new iPhone')."""
country_code: CountryCode | None
"""Optional 2-letter country code to filter news by region \
(e.g., 'us' for United States, 'uk' for United Kingdom)."""
language_code: LanguageCode | None
"""Optional 2-letter language code to filter news by language \
(e.g., 'en' for English, 'es' for Spanish)."""
limit: int | None
"""Optional maximum number of news articles to return. \
If not specified, returns all results from the API."""
class SourceInfo(TypedDict, total=False):
"""Information about the news source/publication."""
name: str
"""Name of the publication (e.g., 'CNN', 'BBC News', 'The New York Times')."""
icon: str
"""URL to the source's favicon or logo image."""
authors: list[str]
"""List of author names for the article, if available."""
class NewsResult(TypedDict, total=False):
"""Individual news article from the Google News API response."""
position: int
"""Ranking position of this result in the search results."""
title: str
"""Headline or title of the news article."""
link: str
"""Full URL to the original news article."""
source: SourceInfo
"""Information about the publication source."""
date: str
"""Publication date and time (e.g., '2 hours ago', 'Dec 15, 2023')."""
snippet: str
"""Brief excerpt or summary from the article content."""
thumbnail: str
"""URL to a high-resolution thumbnail image for the article."""
thumbnail_small: str
"""URL to a low-resolution thumbnail image for the article."""
story_token: str
"""Token for accessing full coverage of this news story across multiple sources."""
stories: list["NewsResult"]
"""Related news stories from other sources covering the same topic."""
highlight: dict
"""Additional highlighted information about the story."""
class SearchMetadata(TypedDict, total=False):
"""Metadata about the search request and processing."""
id: str
"""Unique identifier for this search request within SerpApi."""
status: str
"""Current processing status ('Processing', 'Success', or 'Error')."""
json_endpoint: str
"""URL to retrieve the JSON results for this search."""
created_at: str
"""Timestamp when the search request was created."""
processed_at: str
"""Timestamp when the search request was processed."""
google_news_url: str
"""Original Google News URL that would return these results."""
total_time_taken: float
"""Total time in seconds taken to process this search."""
class SearchParameters(TypedDict, total=False):
"""Parameters used for the search request."""
engine: str
"""Search engine used (always 'google_news' for this API)."""
q: str
"""Search query string."""
gl: str
"""Country code used for geographic filtering."""
hl: str
"""Language code used for language filtering."""
topic_token: str
"""Token for accessing specific news topics (e.g., 'World', 'Business', 'Technology')."""
publication_token: str
"""Token for accessing news from specific publishers."""
class MenuLink(TypedDict):
"""Navigation link for news categories or topics."""
title: str
"""Display text for the menu item (e.g., 'Technology', 'Sports', 'Business')."""
topic_token: str
"""Token to access this specific topic or category."""
serpapi_link: str
"""SerpApi URL to search within this topic."""
class TopStoriesLink(TypedDict):
"""Link to top stories section."""
topic_token: str
"""Token to access top stories."""
serpapi_link: str
"""SerpApi URL to retrieve top stories."""
class GoogleNewsResponse(TypedDict, total=False):
"""Complete response from the Google News API."""
search_metadata: SearchMetadata
"""Metadata about the search request and processing."""
search_parameters: SearchParameters
"""Parameters that were used for this search."""
news_results: list[NewsResult]
"""List of news articles matching the search criteria."""
menu_links: list[MenuLink]
"""Navigation links to different news categories and topics."""
top_stories_link: TopStoriesLink
"""Link to access top stories."""
title: str
"""Title of the page or topic being displayed."""
class SimplifiedNewsResult(TypedDict):
"""Simplified news article format for tool output."""
title: str
"""Headline of the news article."""
link: str
"""URL to the full article."""
source: str | None
"""Name of the publication source."""
date: str | None
"""When the article was published."""
snippet: str | None
"""Brief excerpt from the article."""
class SearchNewsOutput(TypedDict):
"""Output format for the search_news_stories tool."""
news_results: list[SimplifiedNewsResult]
"""List of news articles in simplified format."""
@tool(requires_secrets=["SERP_API_KEY"])
async def search_news_stories(
context: ToolContext,
keywords: Annotated[
str,
"Keywords to search for news articles. E.g. 'Apple launches new iPhone'.",
],
country_code: Annotated[
CountryCode | None,
"2-character country code to search for news articles. "
"E.g. 'us' (United States). "
f"Defaults to '{DEFAULT_GOOGLE_NEWS_COUNTRY}'.",
] = None,
language_code: Annotated[
LanguageCode,
"2-character language code to search for news articles. E.g. 'en' (English). "
f"Defaults to '{DEFAULT_GOOGLE_NEWS_LANGUAGE}'.",
] = DEFAULT_GOOGLE_NEWS_LANGUAGE,
limit: Annotated[
int | None,
"Maximum number of news articles to return. Defaults to None "
"(returns all results found by the API).",
] = None,
) -> Annotated[SearchNewsOutput, "News search results with article details."]:
"""Search for news articles related to a given query."""
...
```
### Enhanced Tool Definition: ``GoogleNews.SearchNewsStories``
```json
{
"name": "SearchNewsStories",
"fully_qualified_name": "GoogleNews.SearchNewsStories",
"description": "Search for news articles related to a given query.",
"toolkit": {
"name": "GoogleNews",
"description": "Arcade.dev LLM tools for getting new via Google News",
"version": "2.0.0"
},
"input": {
"parameters": [
{
"name": "keywords",
"required": true,
"description": "Keywords to search for news articles. E.g. 'Apple launches new iPhone'.",
"value_schema": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
"properties": null,
"inner_properties": null,
"description": null
},
"inferrable": true
},
{
"name": "country_code",
"required": false,
"description": "2-character country code to search for news articles. E.g. 'us' (United States). Defaults to 'None'.",
"value_schema": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
"properties": null,
"inner_properties": null,
"description": null
},
"inferrable": true
},
{
"name": "language_code",
"required": false,
"description": "2-character language code to search for news articles. E.g. 'en' (English). Defaults to 'en'.",
"value_schema": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
"properties": null,
"inner_properties": null,
"description": null
},
"inferrable": true
},
{
"name": "limit",
"required": false,
"description": "Maximum number of news articles to return. Defaults to None (returns all results found by the API).",
"value_schema": {
"val_type": "integer",
"inner_val_type": null,
"enum": null,
"properties": null,
"inner_properties": null,
"description": null
},
"inferrable": true
}
]
},
"output": {
"description": "News search results with article details.",
"available_modes": [
"value",
"error"
],
"value_schema": {
"val_type": "json",
"inner_val_type": null,
"enum": null,
"properties": {
"news_results": {
"val_type": "array",
"inner_val_type": "json",
"enum": null,
"properties": null,
"inner_properties": {
"title": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
"properties": null,
"inner_properties": null,
"description": "Headline of the news article."
},
"link": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
"properties": null,
"inner_properties": null,
"description": "URL to the full article."
},
"source": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
"properties": null,
"inner_properties": null,
"description": "Name of the publication source."
},
"date": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
"properties": null,
"inner_properties": null,
"description": "When the article was published."
},
"snippet": {
"val_type": "string",
"inner_val_type": null,
"enum": null,
"properties": null,
"inner_properties": null,
"description": "Brief excerpt from the article."
}
},
"description": "List of news articles in simplified format."
}
},
"inner_properties": null,
"description": null
}
},
"requirements": {
"authorization": null,
"secrets": [
{
"key": "serp_api_key"
}
],
"metadata": null
},
"deprecation_message": null
},
```
---------
Co-authored-by: Eric Gustin <eric@arcade.dev>
281 lines
6.7 KiB
Python
281 lines
6.7 KiB
Python
COUNTRY_CODES: dict[str, str] = {
|
|
"af": "Afghanistan",
|
|
"al": "Albania",
|
|
"dz": "Algeria",
|
|
"as": "American Samoa",
|
|
"ad": "Andorra",
|
|
"ao": "Angola",
|
|
"ai": "Anguilla",
|
|
"aq": "Antarctica",
|
|
"ag": "Antigua and Barbuda",
|
|
"ar": "Argentina",
|
|
"am": "Armenia",
|
|
"aw": "Aruba",
|
|
"au": "Australia",
|
|
"at": "Austria",
|
|
"az": "Azerbaijan",
|
|
"bs": "Bahamas",
|
|
"bh": "Bahrain",
|
|
"bd": "Bangladesh",
|
|
"bb": "Barbados",
|
|
"by": "Belarus",
|
|
"be": "Belgium",
|
|
"bz": "Belize",
|
|
"bj": "Benin",
|
|
"bm": "Bermuda",
|
|
"bt": "Bhutan",
|
|
"bo": "Bolivia",
|
|
"ba": "Bosnia and Herzegovina",
|
|
"bw": "Botswana",
|
|
"bv": "Bouvet Island",
|
|
"br": "Brazil",
|
|
"io": "British Indian Ocean Territory",
|
|
"bn": "Brunei Darussalam",
|
|
"bg": "Bulgaria",
|
|
"bf": "Burkina Faso",
|
|
"bi": "Burundi",
|
|
"kh": "Cambodia",
|
|
"cm": "Cameroon",
|
|
"ca": "Canada",
|
|
"cv": "Cape Verde",
|
|
"ky": "Cayman Islands",
|
|
"cf": "Central African Republic",
|
|
"td": "Chad",
|
|
"cl": "Chile",
|
|
"cn": "China",
|
|
"cx": "Christmas Island",
|
|
"cc": "Cocos (Keeling) Islands",
|
|
"co": "Colombia",
|
|
"km": "Comoros",
|
|
"cg": "Congo",
|
|
"cd": "Congo, the Democratic Republic of the",
|
|
"ck": "Cook Islands",
|
|
"cr": "Costa Rica",
|
|
"ci": "Cote D'ivoire",
|
|
"hr": "Croatia",
|
|
"cu": "Cuba",
|
|
"cy": "Cyprus",
|
|
"cz": "Czech Republic",
|
|
"dk": "Denmark",
|
|
"dj": "Djibouti",
|
|
"dm": "Dominica",
|
|
"do": "Dominican Republic",
|
|
"ec": "Ecuador",
|
|
"eg": "Egypt",
|
|
"sv": "El Salvador",
|
|
"gq": "Equatorial Guinea",
|
|
"er": "Eritrea",
|
|
"ee": "Estonia",
|
|
"et": "Ethiopia",
|
|
"fk": "Falkland Islands (Malvinas)",
|
|
"fo": "Faroe Islands",
|
|
"fj": "Fiji",
|
|
"fi": "Finland",
|
|
"fr": "France",
|
|
"gf": "French Guiana",
|
|
"pf": "French Polynesia",
|
|
"tf": "French Southern Territories",
|
|
"ga": "Gabon",
|
|
"gm": "Gambia",
|
|
"ge": "Georgia",
|
|
"de": "Germany",
|
|
"gh": "Ghana",
|
|
"gi": "Gibraltar",
|
|
"gr": "Greece",
|
|
"gl": "Greenland",
|
|
"gd": "Grenada",
|
|
"gp": "Guadeloupe",
|
|
"gu": "Guam",
|
|
"gt": "Guatemala",
|
|
"gg": "Guernsey",
|
|
"gn": "Guinea",
|
|
"gw": "Guinea-Bissau",
|
|
"gy": "Guyana",
|
|
"ht": "Haiti",
|
|
"hm": "Heard Island and Mcdonald Islands",
|
|
"va": "Holy See (Vatican City State)",
|
|
"hn": "Honduras",
|
|
"hk": "Hong Kong",
|
|
"hu": "Hungary",
|
|
"is": "Iceland",
|
|
"in": "India",
|
|
"id": "Indonesia",
|
|
"ir": "Iran, Islamic Republic of",
|
|
"iq": "Iraq",
|
|
"ie": "Ireland",
|
|
"im": "Isle of Man",
|
|
"il": "Israel",
|
|
"it": "Italy",
|
|
"je": "Jersey",
|
|
"jm": "Jamaica",
|
|
"jp": "Japan",
|
|
"jo": "Jordan",
|
|
"kz": "Kazakhstan",
|
|
"ke": "Kenya",
|
|
"ki": "Kiribati",
|
|
"kp": "Korea, Democratic People's Republic of",
|
|
"kr": "Korea, Republic of",
|
|
"kw": "Kuwait",
|
|
"kg": "Kyrgyzstan",
|
|
"la": "Lao People's Democratic Republic",
|
|
"lv": "Latvia",
|
|
"lb": "Lebanon",
|
|
"ls": "Lesotho",
|
|
"lr": "Liberia",
|
|
"ly": "Libyan Arab Jamahiriya",
|
|
"li": "Liechtenstein",
|
|
"lt": "Lithuania",
|
|
"lu": "Luxembourg",
|
|
"mo": "Macao",
|
|
"mk": "Macedonia, the Former Yugosalv Republic of",
|
|
"mg": "Madagascar",
|
|
"mw": "Malawi",
|
|
"my": "Malaysia",
|
|
"mv": "Maldives",
|
|
"ml": "Mali",
|
|
"mt": "Malta",
|
|
"mh": "Marshall Islands",
|
|
"mq": "Martinique",
|
|
"mr": "Mauritania",
|
|
"mu": "Mauritius",
|
|
"yt": "Mayotte",
|
|
"mx": "Mexico",
|
|
"fm": "Micronesia, Federated States of",
|
|
"md": "Moldova, Republic of",
|
|
"mc": "Monaco",
|
|
"mn": "Mongolia",
|
|
"me": "Montenegro",
|
|
"ms": "Montserrat",
|
|
"ma": "Morocco",
|
|
"mz": "Mozambique",
|
|
"mm": "Myanmar",
|
|
"na": "Namibia",
|
|
"nr": "Nauru",
|
|
"np": "Nepal",
|
|
"nl": "Netherlands",
|
|
"an": "Netherlands Antilles",
|
|
"nc": "New Caledonia",
|
|
"nz": "New Zealand",
|
|
"ni": "Nicaragua",
|
|
"ne": "Niger",
|
|
"ng": "Nigeria",
|
|
"nu": "Niue",
|
|
"nf": "Norfolk Island",
|
|
"mp": "Northern Mariana Islands",
|
|
"no": "Norway",
|
|
"om": "Oman",
|
|
"pk": "Pakistan",
|
|
"pw": "Palau",
|
|
"ps": "Palestinian Territory, Occupied",
|
|
"pa": "Panama",
|
|
"pg": "Papua New Guinea",
|
|
"py": "Paraguay",
|
|
"pe": "Peru",
|
|
"ph": "Philippines",
|
|
"pn": "Pitcairn",
|
|
"pl": "Poland",
|
|
"pt": "Portugal",
|
|
"pr": "Puerto Rico",
|
|
"qa": "Qatar",
|
|
"re": "Reunion",
|
|
"ro": "Romania",
|
|
"ru": "Russian Federation",
|
|
"rw": "Rwanda",
|
|
"sh": "Saint Helena",
|
|
"kn": "Saint Kitts and Nevis",
|
|
"lc": "Saint Lucia",
|
|
"pm": "Saint Pierre and Miquelon",
|
|
"vc": "Saint Vincent and the Grenadines",
|
|
"ws": "Samoa",
|
|
"sm": "San Marino",
|
|
"st": "Sao Tome and Principe",
|
|
"sa": "Saudi Arabia",
|
|
"sn": "Senegal",
|
|
"rs": "Serbia",
|
|
"sc": "Seychelles",
|
|
"sl": "Sierra Leone",
|
|
"sg": "Singapore",
|
|
"sk": "Slovakia",
|
|
"si": "Slovenia",
|
|
"sb": "Solomon Islands",
|
|
"so": "Somalia",
|
|
"za": "South Africa",
|
|
"gs": "South Georgia and the South Sandwich Islands",
|
|
"es": "Spain",
|
|
"lk": "Sri Lanka",
|
|
"sd": "Sudan",
|
|
"sr": "Suriname",
|
|
"sj": "Svalbard and Jan Mayen",
|
|
"sz": "Swaziland",
|
|
"se": "Sweden",
|
|
"ch": "Switzerland",
|
|
"sy": "Syrian Arab Republic",
|
|
"tw": "Taiwan, Province of China",
|
|
"tj": "Tajikistan",
|
|
"tz": "Tanzania, United Republic of",
|
|
"th": "Thailand",
|
|
"tl": "Timor-Leste",
|
|
"tg": "Togo",
|
|
"tk": "Tokelau",
|
|
"to": "Tonga",
|
|
"tt": "Trinidad and Tobago",
|
|
"tn": "Tunisia",
|
|
"tr": "Turkiye",
|
|
"tm": "Turkmenistan",
|
|
"tc": "Turks and Caicos Islands",
|
|
"tv": "Tuvalu",
|
|
"ug": "Uganda",
|
|
"ua": "Ukraine",
|
|
"ae": "United Arab Emirates",
|
|
"uk": "United Kingdom",
|
|
"gb": "United Kingdom",
|
|
"us": "United States",
|
|
"um": "United States Minor Outlying Islands",
|
|
"uy": "Uruguay",
|
|
"uz": "Uzbekistan",
|
|
"vu": "Vanuatu",
|
|
"ve": "Venezuela",
|
|
"vn": "Viet Nam",
|
|
"vg": "Virgin Islands, British",
|
|
"vi": "Virgin Islands, U.S.",
|
|
"wf": "Wallis and Futuna",
|
|
"eh": "Western Sahara",
|
|
"ye": "Yemen",
|
|
"zm": "Zambia",
|
|
"zw": "Zimbabwe",
|
|
}
|
|
|
|
|
|
LANGUAGE_CODES: dict[str, str] = {
|
|
"ar": "Arabic",
|
|
"bn": "Bengali",
|
|
"da": "Danish",
|
|
"de": "German",
|
|
"el": "Greek",
|
|
"en": "English",
|
|
"es": "Spanish",
|
|
"fi": "Finnish",
|
|
"fr": "French",
|
|
"hi": "Hindi",
|
|
"hu": "Hungarian",
|
|
"id": "Indonesian",
|
|
"it": "Italian",
|
|
"ja": "Japanese",
|
|
"ko": "Korean",
|
|
"nl": "Dutch",
|
|
"ms": "Malay",
|
|
"no": "Norwegian",
|
|
"pcm": "Nigerian Pidgin",
|
|
"pl": "Polish",
|
|
"pt": "Portuguese",
|
|
"pt-br": "Portuguese (Brazil)",
|
|
"pt-pt": "Portuguese (Portugal)",
|
|
"ru": "Russian",
|
|
"sv": "Swedish",
|
|
"tl": "Filipino",
|
|
"tr": "Turkish",
|
|
"uk": "Ukrainian",
|
|
"zh": "Chinese",
|
|
"zh-cn": "Chinese (Simplified)",
|
|
"zh-tw": "Chinese (Traditional)",
|
|
}
|