Skip to main content
metalworks is a Python package (3.11+). The core install is tiny; heavier dependencies (provider SDKs, the Reddit corpus, the MCP server) live behind extras, so you only install what you use.

​
Most people want this

That gives you the demand-research pipeline (the local corpus reader + the triage and clustering it needs) and a provider SDK. The [research] extra has no provider SDK on its own — pair it with openai, google, or anthropic. Then set that one key (next section) and you’re ready.
One key is enough — whichever provider you use. Embeddings default to a small local model (no API key, downloaded once), so a single chat key gets you a full run. If you have an OpenAI or Google key, metalworks uses its embeddings automatically (higher quality, no download). Either way, you never need a second key.
No API key? Run keyless on your Claude Code login. Install metalworks[research,claude-code] and run with no key set — the chat model and web search fall back to your Claude Code session (the bundled claude CLI). See Run on your Claude Code login.

​
Pick your extras

Install only what your workflow needs — combine them like "metalworks[research,reddit]". If you call something without its extra, metalworks tells you exactly what to install instead of crashing.

​
Set a provider key

Set the key for the provider you installed — metalworks resolves the chat provider from whichever key is present (Anthropic → OpenAI → Google → OpenRouter):
Embeddings need no separate key. The pipeline needs an embeddings model for clustering; with no Google/OpenAI key it uses a local model (fastembed, bundled with [research]), downloaded once on first use: Pre-download the local model so your first run isn’t blocked on it:
Want Google Vertex AI, a local LLM, or any OpenAI-compatible endpoint? See Configuration. Live web search (optional, improves grounding) reads EXA_API_KEY or TAVILY_API_KEY if present. Reddit posting needs REDDIT_CLIENT_ID / REDDIT_CLIENT_SECRET — see Reddit engagement.

​
Check your setup

Reports installed extras, the keys it found, the resolved chat and embedding models, the store path, connected Reddit accounts, and actionable hints (e.g. “key set but extra missing → pip install …”) — so you know you’re ready before you spend a token. metalworks models list shows the same model resolution plus a provider reachability matrix. Next: run your first real report in the Quickstart.