spectraforge

Reads a folder of PDFs and writes intention-driven reading guides.

Requirements

• Node 20 or later
• An LLM backend configured (see below)
• A folder with at least one .pdf

LLM backend

The pipeline calls Claude models. Pick one of:

• Anthropic API (default): export ANTHROPIC_API_KEY.
• AWS Bedrock: export LLM_PROVIDER=bedrock plus standard AWS credentials (AWS_REGION is required; AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or an AWS_PROFILE must also be reachable). If your workspace config uses short model aliases like claude-opus-4-7, set BEDROCK_MODEL_ALIASES to a JSON map from those aliases to full Bedrock model IDs, e.g. '{"claude-opus-4-7":"anthropic.claude-opus-4-7-v1:0"}'.

Install

npm install -g @spectraforge/cli

Usage

spectraforge run ./path/to/pdfs

The first run clones the pipeline into a local workspace and installs its dependencies. Later runs skip that.

Pass an intention to shape the output:

spectraforge run ./pdfs -i "extract risk factors for a non-technical reader"

spectraforge workspace prints the workspace path, where the output lands.

Hand it to Claude Code

Run `spectraforge` on a folder of PDFs. Do the following in order. If any check fails, stop and tell me exactly what is missing.

1. Check that `git` is installed. If not, stop: tell me git is required.
2. Check that `node --version` reports v20 or later. If not, stop: tell me Node 20+ is required.
3. Check the LLM backend:
   - If `LLM_PROVIDER=bedrock` is set, verify `AWS_REGION` (or `AWS_DEFAULT_REGION`) is set and AWS credentials are reachable.
   - Otherwise, verify `ANTHROPIC_API_KEY` is set. If the check fails, stop and tell me what to export.
4. Check whether `spectraforge` is on PATH. If not, run `npm install -g @spectraforge/cli`.
5. Ask me which folder holds the PDFs I want to process.
6. Run `spectraforge run <that-folder>`.
7. Report back: the output location (`spectraforge workspace` prints the workspace path) and any errors that surfaced.