chatgpt-api/readme.md

404 wiersze
24 KiB
Markdown
Czysty Zwykły widok Historia

2024-05-17 01:22:07 +00:00
<p align="center">
2024-06-07 07:13:41 +00:00
<img alt="Agentic" src="/media/agentic-header.jpg" width="308">
2024-05-17 01:22:07 +00:00
</p>
<p align="center">
2024-06-07 07:49:01 +00:00
<em>AI agent stdlib that works with any LLM and TypeScript AI SDK.</em>
2024-05-17 01:22:07 +00:00
</p>
<p align="center">
2024-06-07 07:13:41 +00:00
<a href="https://github.com/transitive-bullshit/agentic/actions/workflows/main.yml"><img alt="Build Status" src="https://github.com/transitive-bullshit/agentic/actions/workflows/main.yml/badge.svg" /></a>
2024-06-04 11:30:36 +00:00
<a href="https://www.npmjs.com/package/@agentic/stdlib"><img alt="NPM" src="https://img.shields.io/npm/v/@agentic/stdlib.svg" /></a>
2024-06-07 07:13:41 +00:00
<a href="https://github.com/transitive-bullshit/agentic/blob/main/license"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue" /></a>
2024-05-17 01:22:07 +00:00
<a href="https://prettier.io"><img alt="Prettier Code Formatting" src="https://img.shields.io/badge/code_style-prettier-brightgreen.svg" /></a>
</p>
2024-06-04 11:30:36 +00:00
# Agentic <!-- omit from toc -->
2024-05-17 01:22:07 +00:00
2024-06-07 07:18:36 +00:00
- [Intro](#intro)
- [Install](#install)
- [AI SDKs](#ai-sdks)
- [Vercel AI SDk](#vercel-ai-sdk)
- [LangChain](#langchain)
- [LlamaIndex](#llamaindex)
- [Firebase Genkit](#firebase-genkit)
- [Dexa Dexter](#dexa-dexter)
- [OpenAI SDK](#openai-sdk)
- [Optimized Imports](#optimized-imports)
2024-06-07 07:18:36 +00:00
- [Services](#services)
2024-08-04 10:43:27 +00:00
- [Client Design Philosophy](#client-design-philosophy)
2024-06-07 07:18:36 +00:00
- [TODO](#todo)
- [Contributors](#contributors)
- [License](#license)
## Intro
2024-06-03 22:09:28 +00:00
2024-08-04 11:58:02 +00:00
The goal of this project is to create a **set of standard AI functions / tools** which are **optimized for both normal TS-usage as well as LLM-based apps** and work with all of the major TS AI SDKs (LangChain, LlamaIndex, Vercel AI SDK, OpenAI SDK, etc).
2024-06-03 22:09:28 +00:00
2024-08-04 10:55:47 +00:00
Agentic clients like `WeatherClient` can be used as normal TS classes:
2024-06-03 22:09:28 +00:00
```ts
import { WeatherClient } from '@agentic/stdlib'
2024-08-04 10:55:47 +00:00
// Requires `process.env.WEATHER_API_KEY` (from weatherapi.com)
const weather = new WeatherClient()
2024-06-03 22:09:28 +00:00
2024-06-06 05:29:30 +00:00
const result = await weather.getCurrentWeather({
2024-06-03 22:09:28 +00:00
q: 'San Francisco'
})
console.log(result)
```
2024-06-07 08:30:18 +00:00
Or you can use these clients as **LLM-based tools** where the LLM decides when and how to invoke the underlying functions for you.
2024-06-06 03:00:30 +00:00
This works across all of the major AI SDKs via adapters. Here's an example using [Vercel's AI SDK](https://github.com/vercel/ai):
2024-06-03 22:09:28 +00:00
```ts
// sdk-specific imports
import { openai } from '@ai-sdk/openai'
import { generateText } from 'ai'
import { createAISDKTools } from '@agentic/ai-sdk'
2024-06-03 22:09:28 +00:00
// sdk-agnostic imports
import { WeatherClient } from '@agentic/stdlib'
const weather = new WeatherClient()
const result = await generateText({
2024-08-04 10:55:47 +00:00
model: openai('gpt-4o-mini'),
// this is the key line which uses the `@agentic/ai-sdk` adapter
2024-06-03 22:09:28 +00:00
tools: createAISDKTools(weather),
toolChoice: 'required',
prompt: 'What is the weather in San Francisco?'
})
console.log(result.toolResults[0])
```
2024-06-06 23:55:19 +00:00
You can use our standard library of thoroughly tested AI functions with your favorite AI SDK – without having to write any glue code!
2024-06-06 03:00:30 +00:00
Here's a slightly more complex example which uses multiple clients and selects a subset of their functions using the `AIFunctionSet.pick` method:
2024-06-03 22:09:28 +00:00
```ts
// sdk-specific imports
import { ChatModel, createAIRunner } from '@dexaai/dexter'
import { createDexterFunctions } from '@agentic/dexter'
2024-06-03 22:09:28 +00:00
// sdk-agnostic imports
import { PerigonClient, SerperClient } from '@agentic/stdlib'
async function main() {
2024-06-06 23:55:19 +00:00
// Perigon is a news API and Serper is a Google search API
2024-06-03 22:09:28 +00:00
const perigon = new PerigonClient()
const serper = new SerperClient()
const runner = createAIRunner({
chatModel: new ChatModel({
2024-08-04 10:55:47 +00:00
params: { model: 'gpt-4o-mini', temperature: 0 }
2024-06-03 22:09:28 +00:00
}),
functions: createDexterFunctions(
perigon.functions.pick('search_news_stories'),
serper
),
2024-08-04 10:55:47 +00:00
systemMessage: 'You are a helpful assistant. Be as concise as possible.'
2024-06-03 22:09:28 +00:00
})
const result = await runner(
'Summarize the latest news stories about the upcoming US election.'
)
console.log(result)
}
```
2024-06-06 03:11:11 +00:00
Here we've exposed 2 functions to the LLM, `search_news_stories` (which comes from the `PerigonClient.searchStories` method) and `serper_google_search` (which implicitly comes from the `SerperClient.search` method).
2024-06-03 22:09:28 +00:00
2024-08-04 10:55:47 +00:00
All of the SDK adapters like `createDexterFunctions` accept very flexible `AIFunctionLike` objects, which include:
2024-06-04 11:30:36 +00:00
- `AIFunctionSet` - Sets of AI functions (like `perigon.functions.pick('search_news_stories')` or `perigon.functions` or `serper.functions`)
- `AIFunctionsProvider` - Client classes which expose an `AIFunctionSet` via the `.functions` property (like `perigon` or `serper`)
2024-06-06 03:11:11 +00:00
- `AIFunction` - Individual functions (like `perigon.functions.get('search_news_stories')` or `serper.functions.get('serper_google_search')` or AI functions created directly via the `createAIFunction` utility function)
2024-06-04 11:30:36 +00:00
2024-06-06 03:11:11 +00:00
You can pass as many of these `AIFunctionLike` objects as you'd like and you can manipulate them as `AIFunctionSet` sets via `.pick`, `.omit`, `.get`, `.map`, etc.
2024-06-03 22:09:28 +00:00
2024-06-07 07:18:36 +00:00
## Install
```sh
npm install @agentic/stdlib @agentic/core zod
2024-06-07 07:18:36 +00:00
```
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and requires `Node.js >= 18` or an equivalent environment (bun, deno, CF workers, etc).
### AI SDKs
2024-08-04 10:55:47 +00:00
Each AI SDK adapter has its own package which needs to be installed.
<details>
<summary>
#### Vercel AI SDk
</summary>
```sh
2024-08-04 10:41:42 +00:00
npm install @agentic/ai-sdk ai
```
```ts
import { createAISDKTools } from '@agentic/ai-sdk'
```
2024-08-04 10:55:47 +00:00
See [examples/ai-sdk](./examples/ai-sdk) for a full example.
</details>
<details>
<summary>
#### LangChain
</summary>
```sh
2024-08-04 10:41:42 +00:00
npm install @agentic/langchain @langchain/core langchain
```
```ts
import { createLangChainTools } from '@agentic/langchain'
```
2024-08-04 10:55:47 +00:00
See [examples/langchain](./examples/langchain) for a full example.
</details>
<details>
<summary>
#### LlamaIndex
</summary>
```sh
2024-08-04 10:41:42 +00:00
npm install @agentic/llamaindex llamaindex
```
```ts
import { createLlamaIndexTools } from '@agentic/llamaindex'
```
2024-08-04 10:55:47 +00:00
See [examples/llamaindex](./examples/llamaindex) for a full example.
</details>
<details>
<summary>
#### Firebase Genkit
</summary>
```sh
2024-08-04 10:41:42 +00:00
npm install @agentic/genkit @genkit-ai/ai @genkit-ai/core
```
```ts
import { createGenkitTools } from '@agentic/genkit'
```
2024-08-04 10:55:47 +00:00
See [examples/genkit](./examples/genkit) for a full example.
</details>
<details>
<summary>
#### Dexa Dexter
</summary>
```sh
2024-08-04 10:41:42 +00:00
npm install @agentic/dexter @dexaai/dexter
```
```ts
import { createDexterFunctions } from '@agentic/dexter'
```
2024-08-04 10:55:47 +00:00
See [examples/dexter](./examples/dexter) for a full example.
</details>
<details>
<summary>
#### OpenAI SDK
</summary>
```sh
npm install openai
```
2024-08-04 10:55:47 +00:00
There's no need for an adapter with the OpenAI SDK since all agentic tools are compatible with OpenAI by default. You can use `AIFunctionSet.specs` for function calling or `AIFunctionSet.toolSpecs` for parallel tool calling.
```ts
import { WeatherClient } from '@agentic/stdlib'
import OpenAI from 'openai'
const weather = new WeatherClient()
const openai = new OpenAI()
const messages: OpenAI.ChatCompletionMessageParam[] = [
{
role: 'system',
content: 'You are a helpful assistant. Be as concise as possible.'
},
{ role: 'user', content: 'What is the weather in San Francisco?' }
]
{
// First call to OpenAI to invoke the weather tool
const res = await openai.chat.completions.create({
messages,
2024-08-04 10:55:47 +00:00
model: 'gpt-4o-mini',
temperature: 0,
tools: weather.functions.toolSpecs,
tool_choice: 'required'
})
const message = res.choices[0]?.message!
console.log(JSON.stringify(message, null, 2))
assert(message.tool_calls?.[0]?.function?.name === 'get_current_weather')
const fn = weather.functions.get('get_current_weather')!
assert(fn)
const toolParams = message.tool_calls[0].function.arguments
const toolResult = await fn(toolParams)
messages.push(message)
messages.push({
role: 'tool',
tool_call_id: message.tool_calls[0].id,
content: JSON.stringify(toolResult)
})
}
{
// Second call to OpenAI to generate a text response
const res = await openai.chat.completions.create({
messages,
2024-08-04 10:55:47 +00:00
model: 'gpt-4o-mini',
temperature: 0,
tools: weather.functions.toolSpecs
})
const message = res.choices?.[0]?.message
console.log(JSON.stringify(message, null, 2))
}
```
2024-08-04 10:55:47 +00:00
See [examples/openai](./examples/openai) for a full example.
</details>
2024-08-04 10:41:42 +00:00
See the [examples](./examples) directory for working examples of how to use each of these adapters.
### Optimized Imports
`@agentic/stdlib` is just a convenience wrapper which re-exports all of the built-in AI tool packages. If you want to optimize your imports, you can replace `@agentic/stdlib` with the specific AI tools you want. For example:
```sh
npm install @agentic/weather @agentic/core zod
```
```ts
import { WeatherClient } from '@agentic/weather'
```
Some of these individual tool packages have peer dependencies if they depend on large, external packages. If so, you'll need to install their peer deps as well.
Take `e2b`, for example, which requires `@e2b/code-interpreter` as a peer dep:
```sh
npm install @agentic/e2b @agentic/core zod @e2b/code-interpreter
```
```ts
import { e2b } from '@agentic/e2b'
```
> [!NOTE]
2024-08-04 10:41:42 +00:00
> There is no functional difference between using `@agentic/stdlib` versus using the individual packages directly. The only difference is if you want to optimize your install size (when running on serverless functions, for instance), in which case installing and using the individual packages directly will be more efficient. The default examples use `@agentic/stdlib` because it provides a simpler DX.
2024-05-23 23:19:38 +00:00
## Services
| Service | Package | Named export | Description |
| ------------------------------------------------------------------------ | --------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Bing](https://www.microsoft.com/en-us/bing/apis/bing-web-search-api) | `@agentic/bing` | `BingClient` | Bing web search. |
| [Calculator](https://github.com/josdejong/mathjs) | `@agentic/calculator` | `calculator` | Basic calculator for simple mathematical expressions. |
| [Clearbit](https://dashboard.clearbit.com/docs) | `@agentic/clearbit` | `ClearbitClient` | Resolving and enriching people and company datae. |
| [Dexa](https://dexa.ai) | `@agentic/dexa` | `DexaClient` | Answers questions from the world's best podcasters. |
| [Diffbot](https://docs.diffbot.com) | `@agentic/diffbot` | `DiffbotClient` | Web page classification and scraping; person and company data enrichment. |
| [E2B](https://e2b.dev) | `@agentic/e2b` | `e2b` | Hosted Python code intrepreter sandbox which is really useful for data analysis, flexible code execution, and advanced reasoning on-the-fly. (_peer dep_ `@e2b/code-interpreter`) |
| [Exa](https://docs.exa.ai) | `@agentic/exa` | `ExaClient` | Web search tailored for LLMs. |
| [Firecrawl](https://www.firecrawl.dev) | `@agentic/firecrawl` | `FirecrawlClient` | Website scraping and sanitization. |
| [HackerNews](https://github.com/HackerNews/API) | `@agentic/hacker-news` | `HackerNewsClient` | Official HackerNews API. |
| [Hunter](https://hunter.io) | `@agentic/hunter` | `HunterClient` | Email finder, verifier, and enrichment. |
| [Jina](https://jina.ai/reader) | `@agentic/jina` | `JinaClient` | Clean URL reader and web search + URL top result reading with a generous free tier. |
| [Midjourney](https://www.imagineapi.dev) | `@agentic/midjourney` | `MidjourneyClient` | Unofficial Midjourney client for generative images. |
| [Novu](https://novu.co) | `@agentic/novu` | `NovuClient` | Sending notifications (email, SMS, in-app, push, etc). |
| [People Data Labs](https://www.peopledatalabs.com) | `@agentic/people-data-labs` | `PeopleDataLabsClient` | People & company data (WIP). |
| [Perigon](https://www.goperigon.com/products/news-api) | `@agentic/perigon` | `PerigonClient` | Real-time news API and web content data from 140,000+ sources. Structured and enriched by AI, primed for LLMs. |
| [Polygon](https://polygon.io) | `@agentic/polygon` | `PolygonClient` | Stock market and company financial data. |
| [PredictLeads](https://predictleads.com) | `@agentic/predict-leads` | `PredictLeadsClient` | In-depth company data including signals like fundraising events, hiring news, product launches, technologies used, etc. |
| [Proxycurl](https://nubela.co/proxycurl) | `@agentic/proxycurl` | `ProxycurlClient` | People and company data from LinkedIn & Crunchbase. |
| [Searxng](https://docs.searxng.org) | `@agentic/searxng` | `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). |
| [SerpAPI](https://serpapi.com/search-api) | `@agentic/serpapi` | `SerpAPIClient` | Lightweight wrapper around SerpAPI for Google search. |
| [Serper](https://serper.dev) | `@agentic/serper` | `SerperClient` | Lightweight wrapper around Serper for Google search. |
| [Slack](https://api.slack.com/docs) | `@agentic/slack` | `SlackClient` | Send and receive Slack messages. |
| [SocialData](https://socialdata.tools) | `@agentic/social-data` | `SocialDataClient` | Unofficial Twitter / X client (readonly) which is much cheaper than the official Twitter API. |
| [Tavily](https://tavily.com) | `@agentic/tavily` | `TavilyClient` | Web search API tailored for LLMs. |
| [Twilio](https://www.twilio.com/docs/conversations/api) | `@agentic/twilio` | `TwilioClient` | Twilio conversation API to send and receive SMS messages. |
| [Twitter](https://developer.x.com/en/docs/twitter-api) | `@agentic/twitter` | `TwitterClient` | Basic Twitter API methods for fetching users, tweets, and searching recent tweets. Includes support for plan-aware rate-limiting. Uses [Nango](https://www.nango.dev) for OAuth support. |
| [Weather](https://www.weatherapi.com) | `@agentic/weather` | `WeatherClient` | Basic access to current weather data based on location. |
| [Wikidata](https://www.wikidata.org/wiki/Wikidata:Data_access) | `@agentic/wikidata` | `WikidataClient` | Basic Wikidata client. |
| [Wikipedia](https://www.mediawiki.org/wiki/API) | `@agentic/wikipedia` | `WikipediaClient` | Wikipedia page search and summaries. |
| [Wolfram Alpha](https://products.wolframalpha.com/llm-api/documentation) | `@agentic/wolfram-alpha` | `WolframAlphaClient` | Wolfram Alpha LLM API client for answering computational, mathematical, and scientific questions. |
Note that you can import any of these AI tools from `@agentic/stdlib` OR from their individual packages. Installing and importing from their individual packages is more efficient, but it's less convenient so it isn't the default.
2024-06-07 07:50:43 +00:00
2024-08-04 10:43:27 +00:00
## Client Design Philosophy
2024-06-06 02:50:19 +00:00
- clients should be as minimal as possible
- clients should use `ky` and `zod` where possible
2024-06-06 05:08:11 +00:00
- clients should have a strongly-typed TS DX
2024-06-06 02:50:19 +00:00
- clients should expose select methods via the `@aiFunction(...)` decorator
2024-06-06 23:55:19 +00:00
- `inputSchema` zod schemas should be as minimal as possible with descriptions prompt engineered specifically for use with LLMs
2024-06-06 02:50:19 +00:00
- clients and AIFunctions should be composable via `AIFunctionSet`
2024-06-06 05:08:11 +00:00
- clients should work with all major TS AI SDKs
2024-06-06 02:50:19 +00:00
2024-05-23 23:19:38 +00:00
## TODO
- services
- browserbase
2024-06-18 08:52:08 +00:00
- [brave search](https://brave.com/search/api/)
2024-06-06 23:55:19 +00:00
- [phantombuster](https://phantombuster.com)
2024-06-09 00:02:37 +00:00
- [apify](https://apify.com/store)
2024-06-06 02:45:48 +00:00
- perplexity
2024-06-06 23:55:19 +00:00
- valtown
2024-06-03 06:19:10 +00:00
- replicate
- huggingface
2024-06-04 23:59:44 +00:00
- [skyvern](https://github.com/Skyvern-AI/skyvern)
2024-06-30 07:31:07 +00:00
- pull from [clay](https://www.clay.com/integrations)
2024-05-23 23:19:38 +00:00
- pull from [langchain](https://github.com/langchain-ai/langchainjs/tree/main/langchain)
2024-06-02 08:06:45 +00:00
- provide a converter for langchain `DynamicStructuredTool`
2024-05-23 23:19:38 +00:00
- pull from [nango](https://docs.nango.dev/integrations/overview)
2024-06-04 23:59:44 +00:00
- pull from [activepieces](https://github.com/activepieces/activepieces/tree/main/packages/pieces/community)
- general openapi support ala [workgpt](https://github.com/team-openpm/workgpt)
- compound tools / chains / flows / runnables
2024-06-03 22:09:28 +00:00
- market maps
- incorporate [zod-validation-error](https://github.com/causaly/zod-validation-error)
2024-06-05 00:58:50 +00:00
- investigate [autotool](https://github.com/run-llama/LlamaIndexTS/tree/main/packages/autotool)
2024-06-09 20:38:51 +00:00
- investigate [alt search engines](https://seirdy.one/posts/2021/03/10/search-engines-with-own-indexes/)
2024-06-05 00:58:50 +00:00
- investigate [data connectors](https://github.com/mendableai/data-connectors)
2024-07-22 04:32:50 +00:00
- add unit tests for individual providers
2024-05-23 23:19:38 +00:00
## Contributors
- [Travis Fischer](https://x.com/transitive_bs)
- [David Zhang](https://x.com/dzhng)
- [Philipp Burckhardt](https://x.com/burckhap)
2024-06-07 08:42:30 +00:00
- And all of the [amazing OSS contributors](https://github.com/transitive-bullshit/agentic/graphs/contributors)!
2024-05-17 01:22:07 +00:00
## License
MIT © [Travis Fischer](https://x.com/transitive_bs)
2024-05-17 01:22:07 +00:00
To stay up to date or learn more, follow [@transitive_bs](https://x.com/transitive_bs) on Twitter.