article

README

Cloudflare AI

This repository contains various packages and demo apps related consuming Cloudflare's AI offerings on the client-side. It is a monorepo powered by Nx and Changesets.

Packages

workers-ai-provider: A custom provider that enables Workers AI's models for the Vercel AI SDK.
ai-gateway-provider: AI Gateway Provider for Vercel AI SDK.

Local Development

Clone the repository.

git clone git@github.com:cloudflare/ai.git

Install Dependencies.

From the root directory, run:
```
cd ai
pnpm install
```
Develop.

To start a development server for a specific app (for instance, tool-calling):
```
pnpm nx dev tool-calling
```
Ideally all commands should be executed from the repository root with the pnpm nx prefix. This will ensure that the dependency graph is managed correctly, e.g. if one package relies on the output of an other.
Testing and Linting.

To execute your continuous integration tests for a specific project (e.g., workers-ai-provider):
```
pnpm nx test:ci workers-ai-provider
```
To lint a specific project:
```
pnpm nx lint my-project
```
To run a more comprehensive sweep of tasks (lint, tests, type checks, build) against one or more projects:
```
pnpm nx run-many -t lint test:ci type-check build -p "my-project other-project"
```

Other Nx Tasks.

build: Compiles a project or a set of projects.
test: Runs project tests in watch mode.
test:ci: Runs tests in CI mode (no watch).
test:smoke: Runs smoke tests.
type-check: Performs TypeScript type checks.

Creating a New Demo App

In order to scaffold a new demo app, you can use the create-demo script. This script will create a new demo app in the demos directory.

pnpm create-demo <demo-name>

After creating the app, pnpm install will be run to install the dependencies, and pnpm nx cf-typegen <demo-name> will be run to generate the types for the demo app. Then it's simply a case of starting the app with:

pnpm nx dev <demo-name>

Contributing

We appreciate contributions and encourage pull requests. Please follow these guidelines:

Project Setup: After forking or cloning, install dependencies with pnpm install.
Branching: Create a new branch for your feature or fix.
Making Changes:

Add or update relevant tests.
On pushing your changes, automated tasks will be run (courtesy of a Husky pre-push hook).

Changesets: If your changes affect a published package, run pnpm changeset to create a changeset. Provide a concise summary of your changes in the changeset prompt.
Pull Request: Submit a pull request to the main branch. The team will review it and merge if everything is in order.

Release Process

This repository uses Changesets to manage versioning and publication:

Changeset Creation: Whenever a change is made that warrants a new release (e.g., bug fixes, new features), run:
```
pnpm changeset
```
Provide a clear description of the changes.
Merging: Once the changeset is merged into main, our GitHub Actions workflows will:

Detect the changed packages, and create a Version Packages PR.
Increment versions automatically (via Changesets).
Publish any package that has a version number to npm. (Demos and other internal items do not require versioning.)

Publication: The release workflow (.github/workflows/release.yml) will run on every push to main. It ensures each published package is tagged and released on npm. Any package with a version field in its package.json will be included in this process.

For any queries or guidance, kindly open an issue or submit a pull request. We hope this structure and process help you to contribute effectively.

ai