From bfab571c92905438d1ff05a0be03becf6fc5b1e8 Mon Sep 17 00:00:00 2001 From: Travis Fischer Date: Fri, 28 Feb 2025 18:30:39 +0700 Subject: [PATCH] feat: add jsdoc comments to aiFunction impls --- package.json | 1 + packages/apollo/src/apollo-client.ts | 7 ++++++ packages/bing/src/bing-client.ts | 3 +++ packages/dexa/src/dexa-client.ts | 3 +++ packages/dexa/src/scraper-client.ts | 3 +++ packages/diffbot/src/diffbot-client.ts | 9 +++++++ packages/firecrawl/src/firecrawl-client.ts | 3 +++ packages/gravatar/src/gravatar-client.ts | 3 +++ .../hacker-news/src/hacker-news-client.ts | 8 ++++++ packages/hunter/src/hunter-client.ts | 9 +++++++ .../jigsawstack/src/jigsawstack-client.ts | 15 +++++++++++ packages/jina/src/jina-client.ts | 6 +++++ packages/leadmagic/src/leadmagic-client.ts | 3 +++ packages/midjourney/src/midjourney-client.ts | 3 +++ .../predict-leads/src/predict-leads-client.ts | 6 +++++ packages/proxycurl/src/proxycurl-client.ts | 8 ++++++ packages/searxng/src/searxng-client.ts | 17 +++++++++++++ packages/serpapi/src/serpapi-client.ts | 3 +++ packages/serper/src/serper-client.ts | 3 +++ packages/twitter/src/twitter-client.ts | 25 +++++++++++++++---- packages/weather/src/weather-client.ts | 3 +++ packages/wikipedia/src/wikipedia-client.ts | 5 ++++ .../wolfram-alpha/src/wolfram-alpha-client.ts | 4 +++ 23 files changed, 145 insertions(+), 5 deletions(-) diff --git a/package.json b/package.json index 509e74b..8699de3 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "dev": "turbo dev --concurrency 50 --continue", "docs": "cd docs && npx mintlify dev", "clean": "turbo clean", + "fix:format": "prettier --write \"**/*.{js,ts,tsx}\"", "test": "turbo test", "test:format": "prettier --check \"**/*.{js,ts,tsx}\"", "test:lint": "turbo test:lint", diff --git a/packages/apollo/src/apollo-client.ts b/packages/apollo/src/apollo-client.ts index 241134c..5dc7d5a 100644 --- a/packages/apollo/src/apollo-client.ts +++ b/packages/apollo/src/apollo-client.ts @@ -311,6 +311,13 @@ export class ApolloClient extends AIFunctionsProvider { }) } + /** + * Attempts to enrich a person with Apollo data. + * + * Apollo relies on the information you pass via the endpoint's parameters to identify the correct person to enrich. If you provide more information about a person, Apollo is more likely to find a match within its database. If you only provide general information, such as a name without a domain or email address, you might receive a 200 response, but the response will indicate that no records have been enriched. + * + * By default, this endpoint does not return personal emails or phone numbers. Use the reveal_personal_emails and reveal_phone_number parameters to retrieve emails and phone numbers. + */ @aiFunction({ name: 'apollo_enrich_person', description: `Attempts to enrich a person with Apollo data. diff --git a/packages/bing/src/bing-client.ts b/packages/bing/src/bing-client.ts index 54d0fcb..d4ffb2f 100644 --- a/packages/bing/src/bing-client.ts +++ b/packages/bing/src/bing-client.ts @@ -275,6 +275,9 @@ export class BingClient extends AIFunctionsProvider { }) } + /** + * Searches the web using the Bing search engine to return the most relevant web pages for a given query. Can also be used to find up-to-date news and information about many topics. + */ @aiFunction({ name: 'bing_web_search', description: diff --git a/packages/dexa/src/dexa-client.ts b/packages/dexa/src/dexa-client.ts index 74dc1f8..24438ec 100644 --- a/packages/dexa/src/dexa-client.ts +++ b/packages/dexa/src/dexa-client.ts @@ -49,6 +49,9 @@ export class DexaClient extends AIFunctionsProvider { this.ky = ky.extend({ prefixUrl: this.apiBaseUrl, timeout: timeoutMs }) } + /** + * Answers questions based on knowledge of trusted experts and podcasters. Example experts include: Andrew Huberman, Tim Ferriss, Lex Fridman, Peter Attia, Seth Godin, Rhonda Patrick, Rick Rubin, and more. + */ @aiFunction({ name: 'ask_dexa', description: diff --git a/packages/dexa/src/scraper-client.ts b/packages/dexa/src/scraper-client.ts index b1a1720..c806ba6 100644 --- a/packages/dexa/src/scraper-client.ts +++ b/packages/dexa/src/scraper-client.ts @@ -80,6 +80,9 @@ export class ScraperClient extends AIFunctionsProvider { this.ky = throttledKy.extend({ prefixUrl: this.apiBaseUrl }) } + /** + * Scrapes the content of a single URL. + */ @aiFunction({ name: 'scrape_url', description: 'Scrapes the content of a single URL.', diff --git a/packages/diffbot/src/diffbot-client.ts b/packages/diffbot/src/diffbot-client.ts index fef1fde..001eb78 100644 --- a/packages/diffbot/src/diffbot-client.ts +++ b/packages/diffbot/src/diffbot-client.ts @@ -661,6 +661,9 @@ export class DiffbotClient extends AIFunctionsProvider { }) } + /** + * Scrapes and extracts structured data from a web page. Also classifies the web page as one of several types (article, product, discussion, job, image, video, list, event, or other). + */ @aiFunction({ name: 'diffbot_analyze_url', description: @@ -673,6 +676,9 @@ export class DiffbotClient extends AIFunctionsProvider { return this._extract('v3/analyze', options) } + /** + * Scrapes and extracts clean article text from news articles, blog posts, and other text-heavy web pages. + */ @aiFunction({ name: 'diffbot_extract_article_from_url', description: @@ -685,6 +691,9 @@ export class DiffbotClient extends AIFunctionsProvider { return this._extract('v3/article', options) } + /** + * Resolves and enriches a partial person or organization entity. + */ @aiFunction({ name: 'diffbot_enhance_entity', description: diff --git a/packages/firecrawl/src/firecrawl-client.ts b/packages/firecrawl/src/firecrawl-client.ts index cda6d6d..3b7c65e 100644 --- a/packages/firecrawl/src/firecrawl-client.ts +++ b/packages/firecrawl/src/firecrawl-client.ts @@ -145,6 +145,9 @@ export class FirecrawlClient extends AIFunctionsProvider { }) } + /** + * Scrape the contents of a URL. + */ @aiFunction({ name: 'firecrawl_scrape_url', description: 'Scrape the contents of a URL.', diff --git a/packages/gravatar/src/gravatar-client.ts b/packages/gravatar/src/gravatar-client.ts index 2148cdd..277d368 100644 --- a/packages/gravatar/src/gravatar-client.ts +++ b/packages/gravatar/src/gravatar-client.ts @@ -160,6 +160,9 @@ export class GravatarClient extends AIFunctionsProvider { }) } + /** + * Get Gravatar profile by email. Returns a profile object or `undefined` if not found. + */ @aiFunction({ name: 'gravatar_get_profile', description: diff --git a/packages/hacker-news/src/hacker-news-client.ts b/packages/hacker-news/src/hacker-news-client.ts index 445637e..d3bbddd 100644 --- a/packages/hacker-news/src/hacker-news-client.ts +++ b/packages/hacker-news/src/hacker-news-client.ts @@ -271,6 +271,7 @@ export class HackerNewsClient extends AIFunctionsProvider { }) } + /** Fetches a HN story or comment by its ID. */ @aiFunction({ name: 'hacker_news_get_item', description: 'Fetches a HN story or comment by its ID.', @@ -287,6 +288,9 @@ export class HackerNewsClient extends AIFunctionsProvider { .json() } + /** + * Fetches a HN user by username. + */ @aiFunction({ name: 'hacker_news_get_user', description: 'Fetches a HN user by username.', @@ -303,6 +307,7 @@ export class HackerNewsClient extends AIFunctionsProvider { .json() } + /** Searches HN for stories and comments matching the given query. */ @aiFunction({ name: 'hacker_news_search', description: @@ -342,6 +347,9 @@ export class HackerNewsClient extends AIFunctionsProvider { .json() } + /** + * Fetches / searches the top stories currently on the front page of HN. This is the same as `hacker_news_search`, but with `tags: ["front_page"]` set to filter only by the current front page stories. + */ @aiFunction({ name: 'hacker_news_get_top_stories', description: diff --git a/packages/hunter/src/hunter-client.ts b/packages/hunter/src/hunter-client.ts index d1793bc..2c13ba0 100644 --- a/packages/hunter/src/hunter-client.ts +++ b/packages/hunter/src/hunter-client.ts @@ -249,6 +249,9 @@ export class HunterClient extends AIFunctionsProvider { }) } + /** + * Gets all the email addresses associated with a given company or domain. + */ @aiFunction({ name: 'hunter_domain_search', description: @@ -280,6 +283,9 @@ export class HunterClient extends AIFunctionsProvider { return pruneNullOrUndefinedDeep(res) } + /** + * Finds the most likely email address from a domain name, a first name and a last name. + */ @aiFunction({ name: 'hunter_email_finder', description: @@ -308,6 +314,9 @@ export class HunterClient extends AIFunctionsProvider { return pruneNullOrUndefinedDeep(res) } + /** + * Verifies the deliverability of an email address. + */ @aiFunction({ name: 'hunter_email_verifier', description: 'Verifies the deliverability of an email address.', diff --git a/packages/jigsawstack/src/jigsawstack-client.ts b/packages/jigsawstack/src/jigsawstack-client.ts index 8a48157..0267674 100644 --- a/packages/jigsawstack/src/jigsawstack-client.ts +++ b/packages/jigsawstack/src/jigsawstack-client.ts @@ -155,6 +155,9 @@ export class JigsawStackClient extends AIFunctionsProvider { }) } + /** + * Perform web searches and retrieve high-quality results of the given query + */ @aiFunction({ name: 'jigsawstack_ai_search', description: @@ -173,6 +176,9 @@ export class JigsawStackClient extends AIFunctionsProvider { .json() } + /** + * Scrape any website + */ @aiFunction({ name: 'jigsawstack_ai_scrape', description: 'Scrape any website', @@ -195,6 +201,9 @@ export class JigsawStackClient extends AIFunctionsProvider { .json() } + /** + * Recognise, describe and retrieve data within an image with great accuracy. + */ @aiFunction({ name: 'jigsawstack_vocr', description: @@ -217,6 +226,9 @@ export class JigsawStackClient extends AIFunctionsProvider { .json() } + /** + * Generate semantically correct SQL queries from text. + */ @aiFunction({ name: 'jigsawstack_text_to_sql', description: 'Generate semantically correct SQL queries from text.', @@ -241,6 +253,9 @@ export class JigsawStackClient extends AIFunctionsProvider { .json() } + /** + * Convert audio/video files into accurate text transcriptions instantly. + */ @aiFunction({ name: 'jigsawstack_speech_to_text', description: diff --git a/packages/jina/src/jina-client.ts b/packages/jina/src/jina-client.ts index 81ff3de..87186cd 100644 --- a/packages/jina/src/jina-client.ts +++ b/packages/jina/src/jina-client.ts @@ -158,6 +158,9 @@ export class JinaClient extends AIFunctionsProvider { this.kySearch = throttledKySearch.extend({ prefixUrl: 'https://s.jina.ai' }) } + /** + * Reads the contents of the given URL and returns it's main contents in a clean, LLM-friendly format. + */ @aiFunction({ name: 'readUrl', description: @@ -198,6 +201,9 @@ export class JinaClient extends AIFunctionsProvider { } } + /** + * Searches the web for the given query and returns the top-5 results including their page contents in a clean, LLM-friendly format. + */ @aiFunction({ name: 'search', description: diff --git a/packages/leadmagic/src/leadmagic-client.ts b/packages/leadmagic/src/leadmagic-client.ts index 6d42e70..09d75d5 100644 --- a/packages/leadmagic/src/leadmagic-client.ts +++ b/packages/leadmagic/src/leadmagic-client.ts @@ -97,6 +97,9 @@ export class LeadMagicClient extends AIFunctionsProvider { }) } + /** + * Attempts to enrich a person with LeadMagic data based on their public LinkedIn username / identifier. + */ @aiFunction({ name: 'leadmagic_profile_search', description: diff --git a/packages/midjourney/src/midjourney-client.ts b/packages/midjourney/src/midjourney-client.ts index 85dee86..b3a1b5b 100644 --- a/packages/midjourney/src/midjourney-client.ts +++ b/packages/midjourney/src/midjourney-client.ts @@ -79,6 +79,9 @@ export class MidjourneyClient extends AIFunctionsProvider { }) } + /** + * Creates 4 images from a prompt using the Midjourney API. Useful for generating images on the fly. + */ @aiFunction({ name: 'midjourney_create_images', description: diff --git a/packages/predict-leads/src/predict-leads-client.ts b/packages/predict-leads/src/predict-leads-client.ts index 97957f6..8313e69 100644 --- a/packages/predict-leads/src/predict-leads-client.ts +++ b/packages/predict-leads/src/predict-leads-client.ts @@ -526,6 +526,9 @@ export class PredictLeadsClient extends AIFunctionsProvider { }) } + /** + * Returns basic information about a company given its `domain` like location, name, stock ticker, description, etc. + */ @aiFunction({ name: 'get_company', description: @@ -541,6 +544,9 @@ export class PredictLeadsClient extends AIFunctionsProvider { return this.ky.get(`v2/companies/${domain}`).json() } + /** + * Returns a list of events from news for a given company. Events are found in press releases, industry news, blogs, social media, and other online sources. + */ @aiFunction({ name: 'get_company_events', description: diff --git a/packages/proxycurl/src/proxycurl-client.ts b/packages/proxycurl/src/proxycurl-client.ts index 067ef7d..ffd4bc7 100644 --- a/packages/proxycurl/src/proxycurl-client.ts +++ b/packages/proxycurl/src/proxycurl-client.ts @@ -2108,6 +2108,7 @@ export class ProxycurlClient extends AIFunctionsProvider { }) } + /** Gets the LinkedIn profile for a company given it's domain `url`. */ @aiFunction({ name: 'get_linkedin_company', description: @@ -2134,6 +2135,7 @@ export class ProxycurlClient extends AIFunctionsProvider { } } + /** Gets the LinkedIn profile for a person given some unique, identifying information about them. */ @aiFunction({ name: 'get_linkedin_person', description: @@ -2150,6 +2152,7 @@ export class ProxycurlClient extends AIFunctionsProvider { .json() } + /** Resolves the LinkedIn profile for a person given their `first_name` and `company_domain` URL. */ @aiFunction({ name: 'resolve_linkedin_person', description: @@ -2170,6 +2173,7 @@ export class ProxycurlClient extends AIFunctionsProvider { .json() } + /** Resolves the LinkedIn profile for a person given their `email`. */ @aiFunction({ name: 'resolve_linkedin_person_by_email', description: @@ -2189,6 +2193,7 @@ export class ProxycurlClient extends AIFunctionsProvider { .json() } + /** Resolves the LinkedIn profile for a person at a given `company_name` and `role`. */ @aiFunction({ name: 'resolve_linkedin_person_at_company_by_role', description: @@ -2208,6 +2213,7 @@ export class ProxycurlClient extends AIFunctionsProvider { .json() } + /** Resolves the LinkedIn profile for a company given the `company_name` and/or `company_domain`. */ @aiFunction({ name: 'resolve_linkedin_company', description: @@ -2232,6 +2238,7 @@ export class ProxycurlClient extends AIFunctionsProvider { } } + /** Searches LinkedIn company profiles based on a set of criteria such as `name`, `industry`, `region`, `description`, `city`, number of employees, founding date, funding raised, etc. */ @aiFunction({ name: 'search_linkedin_companies', description: @@ -2246,6 +2253,7 @@ export class ProxycurlClient extends AIFunctionsProvider { .json() } + /** Searches LinkedIn people profiles based on a set of criteria such as `country`, `first_name`, `last_name`, `current_company_name`, `headline`, `industries`, `past_company_name`, `summary`, `city`, `education_school_name`, etc. */ @aiFunction({ name: 'search_linkedin_people', description: diff --git a/packages/searxng/src/searxng-client.ts b/packages/searxng/src/searxng-client.ts index 33bf73e..9b69923 100644 --- a/packages/searxng/src/searxng-client.ts +++ b/packages/searxng/src/searxng-client.ts @@ -307,6 +307,23 @@ export class SearxngClient extends AIFunctionsProvider { this.ky = ky.extend({ prefixUrl: apiBaseUrl }) } + /** + * Searches across multiple search engines using a local instance of Searxng. To search only specific engines, use the `engines` parameter. + * + * The most important search engines are: + * + * - "reddit" (Reddit posts) + * - "google" (Google web search) + * - "google news" (Google News search) + * - "brave" (Brave web search) + * - "arxiv" (academic papers) + * - "genius" (Genius.com for song lyrics) + * - "imdb" (movies and TV shows) + * - "hackernews" (Hacker News) + * - "wikidata" (Wikidata) + * - "wolframalpha" (Wolfram Alpha) + * - "youtube" (YouTube videos) + */ @aiFunction({ name: 'searxng', description: `Searches across multiple search engines using a local instance of Searxng. To search only specific engines, use the \`engines\` parameter. diff --git a/packages/serpapi/src/serpapi-client.ts b/packages/serpapi/src/serpapi-client.ts index 826b218..9a46108 100644 --- a/packages/serpapi/src/serpapi-client.ts +++ b/packages/serpapi/src/serpapi-client.ts @@ -662,6 +662,9 @@ export class SerpAPIClient extends AIFunctionsProvider { }) } + /** + * Uses Google Search to return the most relevant web pages for a given query. Useful for finding up-to-date news and information about any topic. + */ @aiFunction({ name: 'serpapi_google_search', description: diff --git a/packages/serper/src/serper-client.ts b/packages/serper/src/serper-client.ts index 976f565..fd4d7f4 100644 --- a/packages/serper/src/serper-client.ts +++ b/packages/serper/src/serper-client.ts @@ -248,6 +248,9 @@ export class SerperClient extends AIFunctionsProvider { }) } + /** + * Uses Google Search to return the most relevant web pages for a given query. Useful for finding up-to-date news and information about any topic. + */ @aiFunction({ name: 'serper_google_search', description: diff --git a/packages/twitter/src/twitter-client.ts b/packages/twitter/src/twitter-client.ts index 6c7b989..719fffe 100644 --- a/packages/twitter/src/twitter-client.ts +++ b/packages/twitter/src/twitter-client.ts @@ -176,6 +176,9 @@ export class TwitterClient extends AIFunctionsProvider { protected _findUserById: ReturnType protected _findUserByUsername: ReturnType + /** + * Creates a new tweet + */ @aiFunction({ name: 'create_tweet', description: 'Creates a new tweet', @@ -189,6 +192,9 @@ export class TwitterClient extends AIFunctionsProvider { return this._createTweet(params) } + /** + * Fetch a tweet by its ID + */ @aiFunction({ name: 'get_tweet_by_id', description: 'Fetch a tweet by its ID', @@ -196,18 +202,18 @@ export class TwitterClient extends AIFunctionsProvider { id: z.string().min(1) }) }) - async findTweetById({ - id, - ...params - }: { id: string } & types.FindTweetByIdParams) { + async findTweetById(params: { id: string } & types.FindTweetByIdParams) { assert( this.twitterApiPlan !== 'free', 'TwitterClient.findTweetById not supported on free plan' ) - return this._findTweetById(id, params) + return this._findTweetById(params.id, params) } + /** + * Fetch an array of tweets by their IDs + */ @aiFunction({ name: 'get_tweets_by_id', description: 'Fetch an array of tweets by their IDs', @@ -224,6 +230,9 @@ export class TwitterClient extends AIFunctionsProvider { return this._findTweetsById(ids, params) } + /** + * Searches for recent tweets + */ @aiFunction({ name: 'search_recent_tweets', description: 'Searches for recent tweets', @@ -244,6 +253,9 @@ export class TwitterClient extends AIFunctionsProvider { return this._searchRecentTweets(params) } + /** + * Fetch a twitter user by ID + */ @aiFunction({ name: 'get_twitter_user_by_id', description: 'Fetch a twitter user by ID', @@ -263,6 +275,9 @@ export class TwitterClient extends AIFunctionsProvider { return this._findUserById(id, params) } + /** + * Fetch a twitter user by username + */ @aiFunction({ name: 'get_twitter_user_by_username', description: 'Fetch a twitter user by username', diff --git a/packages/weather/src/weather-client.ts b/packages/weather/src/weather-client.ts index 86d5b5a..10c648c 100644 --- a/packages/weather/src/weather-client.ts +++ b/packages/weather/src/weather-client.ts @@ -109,6 +109,9 @@ export class WeatherClient extends AIFunctionsProvider { this.ky = ky.extend({ prefixUrl: apiBaseUrl }) } + /** + * Gets info about the current weather at a given location. + */ @aiFunction({ name: 'get_current_weather', description: 'Gets info about the current weather at a given location.', diff --git a/packages/wikipedia/src/wikipedia-client.ts b/packages/wikipedia/src/wikipedia-client.ts index 8d4fdcf..1694aab 100644 --- a/packages/wikipedia/src/wikipedia-client.ts +++ b/packages/wikipedia/src/wikipedia-client.ts @@ -139,6 +139,8 @@ export class WikipediaClient extends AIFunctionsProvider { }) } + /** + * Searches Wikipedia for pages matching the given query. */ @aiFunction({ name: 'wikipedia_search', description: 'Searches Wikipedia for pages matching the given query.', @@ -157,6 +159,9 @@ export class WikipediaClient extends AIFunctionsProvider { ) } + /** + * Gets a summary of the given Wikipedia page. + */ @aiFunction({ name: 'wikipedia_get_page_summary', description: 'Gets a summary of the given Wikipedia page.', diff --git a/packages/wolfram-alpha/src/wolfram-alpha-client.ts b/packages/wolfram-alpha/src/wolfram-alpha-client.ts index 34c6772..183599c 100644 --- a/packages/wolfram-alpha/src/wolfram-alpha-client.ts +++ b/packages/wolfram-alpha/src/wolfram-alpha-client.ts @@ -63,6 +63,10 @@ export class WolframAlphaClient extends AIFunctionsProvider { }) } + /** + * WolframAlpha understands natural language queries about entities in chemistry, physics, geography, history, art, astronomy, and more. + * WolframAlpha performs mathematical calculations, date and unit conversions, formula solving, etc. + */ @aiFunction({ name: 'ask_wolfram_alpha', description: `