open-index/open-npm huggingface dataset:
npm package: @simulacra-ai/anthropic
Description: Anthropic Claude provider for the Simulacra conversation engine
Latest version: 0.0.9

# Simulacra Anthropic Provider

The Anthropic provider allows Simulacra to use Claude models via the Anthropic API, with support for extended thinking and prompt caching.

## Installation

```bash
npm install @simulacra-ai/core @simulacra-ai/anthropic @anthropic-ai/sdk
```

## Usage

```typescript
import { Conversation } from "@simulacra-ai/core";
import { AnthropicProvider } from "@simulacra-ai/anthropic";
import Anthropic from "@anthropic-ai/sdk";

// create a provider and conversation
const provider = new AnthropicProvider(new Anthropic(), { model: MODEL_NAME });
using conversation = new Conversation(provider);
```

### AnthropicProviderConfig

```typescript
interface AnthropicProviderConfig {
  model: string;
  max_tokens?: number;
  thinking?: { enable: boolean; budget_tokens?: number };
  prompt_caching?: { system_prompt?: boolean; toolkit?: boolean };
  request_options?: Anthropic.RequestOptions | (() => Anthropic.RequestOptions | Promise<Anthropic.RequestOptions>);
}
```

Additional properties (`temperature`, `top_p`, etc.) spread into the API request.

If `max_tokens` is not set, it defaults to 8192.

## Request Options

The `request_options` field passes custom options to every Anthropic SDK call. It accepts a static `Anthropic.RequestOptions` object or a function that returns one (synchronously or as a promise). A function is useful when options need to be computed at request time, for example to resolve a fresh OAuth token.

```typescript
const provider = new AnthropicProvider(new Anthropic(), {
  model,
  request_options: async () => ({
    headers: {
      "x-api-key": null,
      "authorization": `Bearer ${await get_oauth_token()}`, // don't use a Claude Code token here, doing so is against the Anthropic TOS
      "anthropic-beta": "oauth-2025-04-20",
    },
  }),
});
```

## Extended Thinking

Extended thinking captures the model's chain-of-thought reasoning as `ThinkingMessageContent` blocks in the conversation history. This makes the model's reasoning process visible and accessible alongside its regular output.

```typescript
const provider = new AnthropicProvider(new Anthropic(), {
  model,
  max_tokens: 16384,
  thinking: { enable: true, budget_tokens: 10000 },
});
```

Both `thinking` and `redacted_thinking` blocks from the API are converted to Simulacra's `ThinkingMessageContent` type.

## Prompt Caching

Prompt caching is enabled by default. The provider adds `cache_control` markers to the system prompt and tool definitions, avoiding re-processing static content on every turn. Multi-turn conversations benefit because subsequent turns read from the cache at a reduced rate.

```typescript
const provider = new AnthropicProvider(new Anthropic(), {
  model,
  max_tokens: 4096,
  prompt_caching: {
    system_prompt: true, // default
    toolkit: true, // default
  },
});
```

Cache writes cost slightly more per token than standard requests. Caching can be disabled by setting both flags to `false`.

## License

MIT
npm package: @simulacra-ai/cloudflare
Description: Cloudflare AI Gateway provider for the Simulacra conversation engine
Latest version: 0.0.9

# Simulacra Cloudflare Provider

The Cloudflare provider routes Simulacra conversations through a [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/), giving you caching, rate limiting, analytics, and logging on top of any supported upstream provider.

## Installation

```bash
npm install @simulacra-ai/core @simulacra-ai/cloudflare openai
```

## Usage

```typescript
import { Conversation } from "@simulacra-ai/core";
import { CloudflareProvider, createCloudflareClient } from "@simulacra-ai/cloudflare";

// create an OpenAI client routed through Cloudflare AI Gateway
const client = createCloudflareClient("sk-your-openai-key", {
  accountId: "your-cloudflare-account-id",
  gatewayName: "your-gateway-name",
});

// create a provider and conversation
const provider = new CloudflareProvider(client, { model: "gpt-4o" });
using conversation = new Conversation(provider);

await conversation.prompt("Hello!");
```

### CloudflareProviderConfig

```typescript
interface CloudflareProviderConfig {
  model: string;
  max_tokens?: number;
}
```

Additional properties (`temperature`, `top_p`, etc.) spread into the API request.

### CloudflareGatewayConfig

```typescript
interface CloudflareGatewayConfig {
  accountId: string;
  gatewayName: string;
  provider?: string; // defaults to "openai"
}
```

The `provider` field controls the upstream provider path. Supported values include:

- `"openai"` — OpenAI (default)
- `"workers-ai/v1"` — Cloudflare Workers AI
- `"google-ai-studio/v1beta/openai"` — Google AI Studio (Gemini)
- `"azure-openai/{resource}/openai/deployments/{deployment}"` — Azure OpenAI

## Upstream Providers

The gateway proxies requests to any OpenAI-compatible provider. Set the `provider` field and pass the appropriate API key.

### Workers AI

```typescript
const client = createCloudflareClient("your-cloudflare-api-token", {
  accountId: "your-account-id",
  gatewayName: "your-gateway",
  provider: "workers-ai/v1",
});

const provider = new CloudflareProvider(client, {
  model: "@cf/meta/llama-3.1-8b-instruct",
});
```

### Google AI Studio (Gemini)

```typescript
const client = createCloudflareClient("your-google-ai-key", {
  accountId: "your-account-id",
  gatewayName: "your-gateway",
  provider: "google-ai-studio/v1beta/openai",
});

const provider = new CloudflareProvider(client, {
  model: "gemini-2.0-flash",
});
```

## Building the Gateway URL Manually

If you need to construct the OpenAI client yourself, `getCloudflareGatewayBaseURL` returns the base URL for a given gateway configuration.

```typescript
import { getCloudflareGatewayBaseURL } from "@simulacra-ai/cloudflare";
import OpenAI from "openai";

const baseURL = getCloudflareGatewayBaseURL({
  accountId: "your-account-id",
  gatewayName: "your-gateway",
});
// => "https://gateway.ai.cloudflare.com/v1/your-account-id/your-gateway/openai"

const client = new OpenAI({ apiKey: "sk-...", baseURL });
```

## License

MIT
npm package: @simulacra-ai/google
Description: Google Gemini provider for the Simulacra conversation engine
Latest version: 0.0.9

# Simulacra Google Provider

The Google provider allows Simulacra to use Google Gemini models via the Google GenAI SDK, with support for thinking and automatic handling of Gemini's tool call quirks.

## Installation

```bash
npm install @simulacra-ai/core @simulacra-ai/google @google/genai
```

## Usage

```typescript
import { Conversation } from "@simulacra-ai/core";
import { GoogleProvider } from "@simulacra-ai/google";
import { GoogleGenAI } from "@google/genai";

// create a provider and conversation
const provider = new GoogleProvider(new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY }), {
  model: MODEL_NAME,
});
using conversation = new Conversation(provider);
```

### GoogleProviderConfig

```typescript
interface GoogleProviderConfig {
  model: string;
  max_tokens?: number;
  thinking?: { enable: boolean; budget_tokens?: number };
}
```

Additional properties spread into the Gemini `config` object in the API request.

## Thinking

Thinking captures the model's reasoning process as `ThinkingMessageContent` blocks in the conversation history.

```typescript
const provider = new GoogleProvider(sdk, {
  model,
  max_tokens: 8192,
  thinking: { enable: true, budget_tokens: 10000 },
});
```

## GoogleToolCodeContextTransformer

Gemini models sometimes emit tool calls as inline code blocks instead of structured function calls. `GoogleToolCodeContextTransformer` intercepts these and converts them to standard `ToolContent` entries so the workflow engine can execute them normally.

This transformer is bundled with `GoogleProvider` by default as a provider context transformer. To disable it, pass an empty array.

```typescript
const provider = new GoogleProvider(sdk, config, []);
```

## License

MIT
npm package: @simulacra-ai/mcp
Description: MCP (Model Context Protocol) client bridge for the Simulacra conversation engine
Latest version: 0.0.9

# Simulacra MCP Bridge

The MCP (Model Context Protocol) bridge connects Simulacra to MCP tool servers and exposes their tools as Simulacra tool classes, so the model can use them without writing custom tool implementations.

## Installation

```bash
npm install @simulacra-ai/core @simulacra-ai/mcp @modelcontextprotocol/sdk
```

## Usage

```typescript
import { Conversation, WorkflowManager } from "@simulacra-ai/core";
import { McpToolProvider } from "@simulacra-ai/mcp";

// connect to an MCP server
const mcp = new McpToolProvider({
  servers: [
    {
      name: "filesystem",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    },
  ],
});
await mcp.connect();

// add MCP tools to the conversation's toolkit
using conversation = new Conversation(provider);
conversation.toolkit = [...conversation.toolkit, ...mcp.getToolClasses()];
using manager = new WorkflowManager(conversation);

await conversation.prompt("List the files in /tmp");

// disconnect when done
await mcp.disconnect();
```

### Multiple Servers

Multiple MCP servers can be configured at once. Tools from all servers are merged into a single toolkit.

```typescript
const mcp = new McpToolProvider({
  servers: [
    {
      name: "filesystem",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    },
    {
      name: "database",
      command: "node",
      args: ["./my-db-server.js"],
      env: { DATABASE_URL: "postgres://localhost/mydb" },
    },
  ],
});
```

### Tool Overrides

By default, all MCP tools are `parallelizable: true`. Specific tools with side effects or ordering requirements can be overridden.

```typescript
// inside the servers array
{
  name: "database",
  command: "node",
  args: ["./my-db-server.js"],
  tool_overrides: {
    "execute_query": { parallelizable: false },
    "create_table": { parallelizable: false },
  },
}
```

## License

MIT
npm package: @simulacra-ai/openai
Description: OpenAI provider for the Simulacra conversation engine
Latest version: 0.0.9

# Simulacra OpenAI Provider

The OpenAI provider allows Simulacra to use OpenAI models via the OpenAI SDK, including GPT, o1, and o3 series.

## Installation

```bash
npm install @simulacra-ai/core @simulacra-ai/openai openai
```

## Usage

```typescript
import { Conversation } from "@simulacra-ai/core";
import { OpenAIProvider } from "@simulacra-ai/openai";
import OpenAI from "openai";

// create a provider and conversation
const provider = new OpenAIProvider(new OpenAI(), { model: MODEL_NAME });
using conversation = new Conversation(provider);
```

### OpenAIProviderConfig

```typescript
interface OpenAIProviderConfig {
  model: string;
  max_tokens?: number;
}
```

Additional properties (`temperature`, `top_p`, etc.) spread into the API request.

## License

MIT