regxa AI Tool Integration

regxa exports a ready-made packageTool compatible with the Vercel AI SDK. It gives AI agents structured access to package registry data across npm, PyPI, crates.io, RubyGems, Packagist, and Arch Linux.

Step 1: Install Dependencies

npm install regxa ai @ai-sdk/openai  # or any AI SDK provider

Step 2: Register the Tool

Import packageTool from regxa/ai and pass it to the AI SDK:

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { packageTool } from "regxa/ai";

const result = await generateText({
  model: openai("gpt-4o"),
  tools: { package: packageTool },
  prompt: "What are the dependencies of flask 3.1.1?",
});

The tool handles PURL construction, API calls, normalization, and error handling internally.

Step 3: Understand the Operations

The tool accepts a discriminated union input with these operations:

package - Fetch package metadata

{ "operation": "package", "purl": "pkg:npm/lodash" }

Returns: name, description, licenses, repository, latest version, keywords.

versions - List all versions

{ "operation": "versions", "purl": "pkg:cargo/serde" }

Returns: version numbers, publish dates, integrity hashes, status (yanked/deprecated).

dependencies - List dependencies for a version

{ "operation": "dependencies", "purl": "pkg:pypi/flask@3.1.1" }

Returns: dependency names, version constraints, scope (runtime/development/test/build/optional), optional flag.

Note: The PURL must include a version. Without it, the tool returns an error.

maintainers - List package maintainers

{ "operation": "maintainers", "purl": "pkg:gem/rails" }

Returns: login, name, email, role for each maintainer.

bulk-packages - Fetch multiple packages at once

{ "operation": "bulk-packages", "purls": ["pkg:npm/lodash", "pkg:cargo/serde"], "concurrency": 10 }

Returns: map of PURL to package metadata. Fetches up to 50 PURLs concurrently (default concurrency: 15). Failed lookups are silently omitted.

Step 4: Use with Streaming

The tool works with streamText as well:

import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
import { packageTool } from "regxa/ai";

const result = streamText({
  model: openai("gpt-4o"),
  tools: { package: packageTool },
  prompt: "Compare the latest versions of express and fastify",
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

PURL Format Quick Reference

Read references/purl-cheatsheet.md for the PURL format details and ecosystem-specific examples.

Error Handling

The tool throws errors as exceptions (not structured return values). The AI SDK catches these and surfaces them to the agent as tool call failures:

• NotFoundError: Package or version does not exist
• InvalidPURLError: Malformed PURL string (missing pkg: prefix, bad encoding)
• UnknownEcosystemError: Unsupported ecosystem type
• RateLimitError: Registry rate limit hit (the HTTP client retries automatically first)

With multi-step tool use, failed calls appear as tool-error parts and the agent can self-correct (e.g., fix PURL format, try a different ecosystem). If you need custom error handling, wrap the tool's execute function.