feat: documenting services

bin/scratch.ts

@@ -11,7 +11,7 @@ import restoreCursor from 'restore-cursor'
 // import { FirecrawlClient } from '../src/index.js'
 // import { ExaClient } from '../src/index.js'
 // import { DiffbotClient } from '../src/index.js'
-// import { WolframClient } from '../src/index.js'
+// import { WolframAlphaClient } from '../src/index.js'
 // import {
 //   createTwitterV2Client,
 //   TwitterClient
@@ -83,7 +83,7 @@ async function main() {
   // })
   // console.log(JSON.stringify(res, null, 2))
 
-  // const wolfram = new WolframClient()
+  // const wolfram = new WolframAlphaClient()
   // const res = await wolfram.ask({
   //   input: 'population of new york city'
   // })

readme.md

@@ -123,26 +123,29 @@ The SDK-specific imports are all isolated to keep the main `@agentic/stdlib` as
 
 ## Services
 
-- bing
+| Service                                                                  | Client                 | Description                                                                                                                                                                                                                                                   |
-- clearbit
+| ------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-- dexa
+| [Bing](https://www.microsoft.com/en-us/bing/apis/bing-web-search-api)    | `BingClient`           | Bing web search                                                                                                                                                                                                                                               |
-- diffbot
+| [Clearbit](https://dashboard.clearbit.com/docs)                          | `ClearbitClient`       | Resolving and enriching people and company data                                                                                                                                                                                                               |
-- exa
+| [Dexa](https://dexa.ai)                                                  | `DexaClient`           | Answers questions from the world's best podcasters                                                                                                                                                                                                            |
-- firecrawl
+| [Diffbot](https://docs.diffbot.com)                                      | `DiffbotClient`        | Web page classification and scraping; person and company data enrichment                                                                                                                                                                                      |
-- midjourney (unofficial API)
+| [Exa](https://docs.exa.ai)                                               | `ExaClient`            | Web search tailored for LLMs                                                                                                                                                                                                                                  |
-- novu
+| [Firecrawl](https://www.firecrawl.dev)                                   | `FirecrawlClient`      | Website scraping and sanitization                                                                                                                                                                                                                             |
-- people data labs (WIP)
+| [Midjourney](https://www.imagineapi.dev)                                 | `MidjourneyClient`     | Unofficial Midjourney client for generative images                                                                                                                                                                                                            |
-- perigon
+| [Novu](https://novu.co)                                                  | `NovuClient`           | Sending notifications (email, SMS, in-app, push, etc)                                                                                                                                                                                                         |
-- predict leads
+| [People Data Labs](https://www.peopledatalabs.com)                       | `PeopleDataLabsClient` | People & company data (WIP)                                                                                                                                                                                                                                   |
-- proxycurl
+| [Perigon](https://www.goperigon.com/products/news-api)                   | `PerigonClient`        | Real-time news API and web content data from 140,000+ sources. Structured and enriched by AI, primed for LLMs.                                                                                                                                                |
-- scraper
+| [Polygon](https://polygon.io)                                            | `PolygonClient`        | Stock market and company financial data                                                                                                                                                                                                                       |
-- searxng
+| [PredictLeads](https://predictleads.com)                                 | `PredictLeadsClient`   | In-depth company data including signals like fundraising events, hiring news, product launches, technologies used, etc                                                                                                                                        |
-- serpapi
+| [Proxycurl](https://nubela.co/proxycurl)                                 | `ProxycurlClient`      | People and company data from LinkedIn & Crunchbase                                                                                                                                                                                                            |
-- serper
+| Scraper                                                                  | `ScraperClient`        | Scrapes URLs into clean html/markdown/text content (TODO: currently closed beta)                                                                                                                                                                              |
-- twitter
+| [Searxng](https://docs.searxng.org)                                      | `SearxngClient`        | OSS meta search engine capable of searching across many providers like Reddit, Google, Brave, Arxiv, Genius, IMDB, Rotten Tomatoes, Wikidata, Wolfram Alpha, YouTube, GitHub, [etc](https://docs.searxng.org/user/configured_engines.html#configured-engines) |
-- wolfram alpha
+| [SerpAPI](https://serpapi.com/search-api)                                | `SerpAPIClient`        | Lightweight wrapper around SerpAPI for Google search                                                                                                                                                                                                          |
-- weatherapi
+| [Serper](https://serper.dev)                                             | `SerperClient`         | Lightweight wrapper around Serper for Google search                                                                                                                                                                                                           |
-- wikipedia
+| [Twitter](https://developer.x.com/en/docs/twitter-api)                   | `TwitterClient`        | Basic Twitter API methods for fetching users, tweets, and searching recent tweets. Includes support for plan-aware rate-limiting.                                                                                                                             |
+| [WeatherAPI](https://api.weatherapi.com)                                 | `WeatherClient`        | Basic access to current weather data based on location                                                                                                                                                                                                        |
+| [Wikipedia](https://www.mediawiki.org/wiki/API)                          | `WikipediaClient`      | Wikipedia page search and summaries                                                                                                                                                                                                                           |
+| [Wolfram Alpha](https://products.wolframalpha.com/llm-api/documentation) | `WolframAlphaClient`   | Wolfram Alpha LLM API client for answering computational, mathematical, and scientific questions.                                                                                                                                                             |
 
 ## Non-service Tools
 

src/services/bing-client.ts

@@ -238,6 +238,11 @@ export namespace bing {
   }
 }
 
+/**
+ * Bing web search client.
+ *
+ * @see https://www.microsoft.com/en-us/bing/apis/bing-web-search-api
+ */
 export class BingClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance
   protected readonly apiKey: string

src/services/clearbit-client.ts

@@ -360,6 +360,11 @@ export namespace clearbit {
   }
 }
 
+/**
+ * The Clearbit API helps with resolving and enriching people and company data.
+ *
+ * @see https://dashboard.clearbit.com/docs
+ */
 export class ClearbitClient {
   protected readonly ky: KyInstance
   protected readonly apiKey: string

src/services/dexa-client.ts

@@ -12,6 +12,12 @@ export namespace dexa {
   export type AskDexaOptions = z.infer<typeof AskDexaOptionsSchema>
 }
 
+/**
+ * Dexa provides answers from the world's best podcasters.
+ *
+ * @note The Dexa API is not yet publicly available.
+ * @see https://dexa.ai
+ */
 export class DexaClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance
   protected readonly apiKey: string

src/services/diffbot-client.ts

@@ -659,6 +659,13 @@ export namespace diffbot {
   }
 }
 
+/**
+ * Diffbot provides web page classification and scraping. It also provides
+ * access to a knowledge graph with the ability to perform person and company
+ * data enrichment.
+ *
+ * @see https://docs.diffbot.com
+ */
 export class DiffbotClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance
   protected readonly kyKnowledgeGraph: KyInstance

src/services/exa-client.ts

@@ -163,6 +163,11 @@ export namespace exa {
   }
 }
 
+/**
+ * Web search tailored for LLMs.
+ *
+ * @see https://docs.exa.ai
+ */
 export class ExaClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance
   protected readonly apiKey: string

src/services/firecrawl-client.ts

@@ -5,9 +5,6 @@ import { aiFunction, AIFunctionsProvider } from '../fns.js'
 import { assert, delay, getEnv } from '../utils.js'
 import { zodToJsonSchema } from '../zod-to-json-schema.js'
 
-// TODO: Deprioritizing this client for now because the API doesn't seem to be
-// stable.
-
 export namespace firecrawl {
   /**
    * Generic parameter interface.
@@ -84,6 +81,9 @@ export namespace firecrawl {
 }
 
 /**
+ * Turn websites into LLM-ready data. Crawl and convert any website into clean
+ * markdown or structured data.
+ *
  * @see https://www.firecrawl.dev
  * @see https://github.com/mendableai/firecrawl
  */

src/services/index.ts

@@ -8,6 +8,7 @@ export * from './midjourney-client.js'
 export * from './novu-client.js'
 export * from './people-data-labs-client.js'
 export * from './perigon-client.js'
+export * from './polygon-client.js'
 export * from './predict-leads-client.js'
 export * from './proxycurl-client.js'
 export * from './scraper-client.js'
@@ -16,4 +17,4 @@ export * from './serpapi-client.js'
 export * from './serper-client.js'
 export * from './weather-client.js'
 export * from './wikipedia-client.js'
-export * from './wolfram-client.js'
+export * from './wolfram-alpha-client.js'

src/services/midjourney-client.ts

@@ -39,7 +39,7 @@ export namespace midjourney {
 }
 
 /**
- * Unofficial Midjourney API client.
+ * Unofficial Midjourney API client for generative images.
  *
  * @see https://www.imagineapi.dev
  */

src/services/novu-client.ts

@@ -91,8 +91,8 @@ export namespace novu {
 }
 
 /**
- * Client for interacting with the Novu API, a router for sending notifications
+ * The Novu API provides a router for sending notifications across different
- * across different channels like Email, SMS, Chat, In-App, and Push.
+ * channels like Email, SMS, Chat, In-App, and Push.
  *
  * @see https://novu.co
  */

src/services/predict-leads-client.ts

@@ -475,6 +475,13 @@ export namespace predictleads {
   >
 }
 
+/**
+ * In-depth company data, including signals like fundraising announcemnts,
+ * hiring intent, new customers signed, technologies used, product launches,
+ * location expansions, awards received, etc.
+ *
+ * @see https://predictleads.com
+ */
 export class PredictLeadsClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance
   protected readonly apiKey: string

src/services/proxycurl-client.ts

@@ -2010,6 +2010,13 @@ export namespace proxycurl {
   export type CompanySearchResult = z.infer<typeof CompanySearchResultSchema>
 }
 
+/**
+ * Pull rich data about people and companies.
+ *
+ * Essentially a wrapper around LinkedIn & Crunchbase.
+ *
+ * @see https://nubela.co/proxycurl/
+ */
 export class ProxycurlClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance
   protected readonly apiKey: string

src/services/scraper-client.ts

@@ -38,6 +38,8 @@ export namespace scraper {
  *
  * It tries the simplest and fastest methods first, and falls back to slower
  * proxies and JavaScript rendering if needed.
+ *
+ * @note This service is currently available only via a closed beta.
  */
 export class ScraperClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance

src/services/searxng-client.ts

@@ -255,11 +255,29 @@ export namespace searxng {
 }
 
 /**
+ * Open source meta search engine capable of searching across many different
+ * sources and search engines.
+ *
+ * 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)
+ * - "github" (GitHub code and repositories)
+ *
  * @see https://docs.searxng.org
  *
  * NOTE: You'll need to run a local instance of Searxng to use this client.
  *
- * See [perplexica](https://github.com/ItzCrazyKns/Perplexica/blob/master/docker-compose.yaml) for an example.
+ * See [perplexica](https://github.com/ItzCrazyKns/Perplexica/blob/master/docker-compose.yaml) for an example of how to set this up.
  */
 export class SearxngClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance

src/services/serpapi-client.ts

@@ -10,7 +10,7 @@ import { assert, getEnv } from '../utils.js'
  */
 
 export namespace serpapi {
-  export const BASE_URL = 'https://serpapi.com'
+  export const API_BASE_URL = 'https://serpapi.com'
 
   export type BaseResponse<P = Record<string | number | symbol, never>> = {
     search_metadata: {
@@ -641,7 +641,7 @@ export class SerpAPIClient extends AIFunctionsProvider {
 
   constructor({
     apiKey = getEnv('SERPAPI_API_KEY') ?? getEnv('SERP_API_KEY'),
-    apiBaseUrl = serpapi.BASE_URL,
+    apiBaseUrl = serpapi.API_BASE_URL,
     ky = defaultKy,
     ...params
   }: {

src/services/serper-client.ts

@@ -5,7 +5,7 @@ import { aiFunction, AIFunctionsProvider } from '../fns.js'
 import { assert, getEnv, omit } from '../utils.js'
 
 export namespace serper {
-  export const BASE_URL = 'https://google.serper.dev'
+  export const API_BASE_URL = 'https://google.serper.dev'
 
   export const SearchParamsSchema = z.object({
     q: z.string().describe('search query'),
@@ -217,7 +217,7 @@ export class SerperClient extends AIFunctionsProvider {
 
   constructor({
     apiKey = getEnv('SERPER_API_KEY'),
-    apiBaseUrl = serper.BASE_URL,
+    apiBaseUrl = serper.API_BASE_URL,
     ky = defaultKy,
     ...params
   }: {

src/services/wikipedia-client.ts

@@ -96,6 +96,11 @@ export namespace wikipedia {
   }
 }
 
+/**
+ * Basic Wikipedia API client for searching wiki pages and resolving page data.
+ *
+ * @see https://www.mediawiki.org/wiki/API
+ */
 export class WikipediaClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance
   protected readonly apiBaseUrl: string

src/services/wolfram-alpha-client.ts

@@ -4,7 +4,7 @@ import { z } from 'zod'
 import { aiFunction, AIFunctionsProvider } from '../fns.js'
 import { assert, getEnv } from '../utils.js'
 
-export namespace wolfram {
+export namespace wolframalpha {
   export const API_BASE_URL = 'https://www.wolframalpha.com/api/'
 
   export const AskWolframAlphaOptionsSchema = z.object({
@@ -28,14 +28,14 @@ export namespace wolfram {
  *
  * @see https://products.wolframalpha.com/llm-api/documentation
  */
-export class WolframClient extends AIFunctionsProvider {
+export class WolframAlphaClient extends AIFunctionsProvider {
   protected readonly ky: KyInstance
   protected readonly appId: string
   protected readonly apiBaseUrl: string
 
   constructor({
     appId = getEnv('WOLFRAM_APP_ID'),
-    apiBaseUrl = wolfram.API_BASE_URL,
+    apiBaseUrl = wolframalpha.API_BASE_URL,
     ky = defaultKy
   }: {
     appId?: string
@@ -44,7 +44,7 @@ export class WolframClient extends AIFunctionsProvider {
   } = {}) {
     assert(
       appId,
-      'WolframClient missing required "appId" (defaults to "WOLFRAM_APP_ID")'
+      'WolframAlphaClient missing required "appId" (defaults to "WOLFRAM_APP_ID")'
     )
     super()
 
@@ -77,9 +77,9 @@ export class WolframClient extends AIFunctionsProvider {
   - Re-send the exact same 'input' with NO modifications, and add the 'assumption' parameter, formatted as a list, with the relevant values.
   - ONLY simplify or rephrase the initial query if a more relevant 'Assumption' or other input suggestions are not provided.
 `.trim(),
-    inputSchema: wolfram.AskWolframAlphaOptionsSchema
+    inputSchema: wolframalpha.AskWolframAlphaOptionsSchema
   })
-  async ask(queryOrOptions: string | wolfram.AskWolframAlphaOptions) {
+  async ask(queryOrOptions: string | wolframalpha.AskWolframAlphaOptions) {
     const options =
       typeof queryOrOptions === 'string'
         ? { input: queryOrOptions }