Imported from jtenner/metidos (core_plugins/fireworks/AGENTS.md). Install upstream with npx skills add jtenner/metidos --skill fireworks. Copyright stays with the author.

AGENTS for Fireworks AI

Purpose

First-party provider plugin for Fireworks AI. It registers a Plugin System v1 model provider and lets Pi use Fireworks's OpenAI-compatible chat completions transport against https://api.fireworks.ai/inference/v1.

Source layout

• metidos-plugin.json: v1 manifest reviewed by the local operator; declares FIREWORKS_API_KEY, the optional api_key plugin setting, network access to Fireworks model discovery, and the fireworks model provider.
• index.ts: plugin entry point that discovers Fireworks models from /inference/v1/models and returns an OpenAI-compatible provider configuration with per-configuration piAuth records.
• AGENTS.md: this guide.
• .data/: generated plugin data owned by Metidos; this plugin does not intentionally create files there.
• .logs/: generated plugin logs if enabled; discovery warnings may be logged there.
• .data-bak-*: generated reset backups; do not commit.

Root node_modules/ is forbidden.

Validation

1. Validate metidos-plugin.json against the Metidos Plugin Manifest v1 schema.
2. Run bun test src/bun/plugin/fireworks-core-plugin.test.ts from the repository root.
3. Confirm no root node_modules/ exists.
4. Confirm imports are local or @metidos/plugin-api.

.data contents

This plugin has no durable plugin-owned data. If .data/ exists, it is runtime-created by Metidos and can be regenerated by Reset Plugin Data.

Safe .data inspection

• Prefer read-only inspection.
• Do not copy or print secret-bearing files if future changes add local credentials.
• Do not edit .data while the plugin sidecar is running unless this guide is updated with an explicit repair workflow.

Safe .data repair

There are no hand-repairable data files today. Prefer Metidos Reset Plugin Data for unknown .data contents; it should be safe because this plugin has no seed data or durable local state.

Reset behavior

Metidos Reset Plugin Data moves .data to .data-bak-{timestamp}, recreates .data, and restarts/reloads the plugin. No local configuration is recreated because credentials live in plugin settings or FIREWORKS_API_KEY.

Secrets and logs

Secrets are provided through the optional secret plugin setting api_key or the secret env var FIREWORKS_API_KEY. Do not log API keys, Authorization headers, prompts, model responses, or request payloads. Discovery failures may log bounded status/error messages only.

Credential precedence for discovery and inference is plugin api_key, then FIREWORKS_API_KEY, as declared in the provider configuration piAuth records.

Embeddings and vector search

This plugin does not provide embedding models, call metidos.embeddings.embed(...), or store LanceDB vectors. The current Fireworks plugin exposes chat-completions models only; embedding support is deferred because the plugin has not implemented and tested the Metidos embedding provider callback contract for Fireworks embeddings. If future changes add embeddings or vector storage, update the manifest and this file together: embedding providers use metidos:provides_embeddings; embedding consumers use metidos:can_embed; vector storage uses metidos:lancedb plus storage:write and must stay scoped to plugin-owned ~/ data.

Context notes

Provider registration is initialization-only. Model discovery uses network:fetch against Fireworks's /inference/v1/models endpoint during provider refresh. Runtime inference is performed by Pi using the registered OpenAI-compatible provider configuration.