AI is optional

SpiderCaster builds every page offline unless you set up an AI provider. With no provider, it runs no model, sends nothing out, and records zero tokens. TokenCTR is SpiderCaster's optional token service: free paths stay the default, and paid credits are spent only if you opt in.

How the AI path works

AI helps plan and patch sections from your own words. The same never-invent rule applies: the planner is told to use only facts from your copy.

Off by default

A build without --offline and with no provider set falls back to the offline build and says so in a warning line.

Stop instead

Add --no-fallback and the build stops with an error when no provider is set, instead of falling back.

Free models first

The chain tries free Gemini models, then free OpenRouter models, then an OpenWork endpoint.

Paid only when allowed

Paid OpenRouter models join the chain only with --allow-paid.

A ledger for every run

report.json records the provider, the model, the requests, the tokens in and out, and an estimated cost.

Turn it on

Providers are set with environment variables. SpiderCaster reads keys by name and never writes them into a site.

Gemini

Set GEMINI_API_KEY with a free key from Google AI Studio.

OpenRouter

Set OPENROUTER_API_KEY. Models whose names end in :free are booked at zero cost.

OpenWork

Set OPENWORK_INFERENCE_BASE_URL and OPENWORK_API_KEY for an endpoint that your organisation provides.

No-key chain

Set SC_AI=on to add the no-key free chain. It is off by default and does not show in the models list in 0.1.0.

See the chain

python spidercaster.py models lists each provider, whether it is set up, and its default models.

With no provider set

The provider list, a build that falls back to offline, and the same build with --no-fallback.

models output
$ python spidercaster.py models
provider chain (free tiers first; paid only with --allow-paid):
  gemini      not configured  Google Gemini (AI Studio free tier / Vertex express)
              models: gemini-2.5-flash-lite, gemini-2.0-flash, gemini-2.5-flash
  openrouter  not configured  OpenRouter
              models: meta-llama/llama-3.3-70b-instruct:free, deepseek/deepseek-chat-v3-0324:free, google/gemini-2.0-flash-exp:free, qwen/qwen-2.5-72b-instruct:free
  openwork    not configured  OpenWork inference (org-provided)
              models: (no models set)

Exit code: 0

build output
$ python spidercaster.py build projects/my-site --out sites/ai-try
  [warn] AI build failed -> offline fallback (no AI provider configured; set GEMINI_API_KEY (free tier) or OPENROUTER_API_KEY, or run with --offline for a zero-token build)
built sites/ai-try (mode: offline-fallback)
  pages: index.html, favicon.svg
  tokens: requests=0 ok=0 in=0 out=0 est_cost=$0.0000
  index: NOINDEX (default; pass --indexable to flip)
  robots: sites/ai-try/robots.txt
  next: python spidercaster.py check sites/ai-try
        python spidercaster.py serve sites/ai-try

Exit code: 0

build output
$ python spidercaster.py build projects/my-site --no-fallback --out sites/ai-try2
no AI provider configured; set GEMINI_API_KEY (free tier) or OPENROUTER_API_KEY, or run with --offline for a zero-token build

Exit code: 1

Where AI is used

Two commands can call a model, and both have a zero-token path.

build

Plans the whole site from your words. With --offline it uses the rule-based planner instead, at zero tokens.

refine

Patches one section of a built site at a small token cost. With --offline it changes the theme only, at zero tokens.

Preview first

--dry-run on build or refine shows the planned change at zero tokens and writes nothing.

TokenCTR, the optional token service

Version 0.1.0 ships without the TokenCTR provider. SC AI Chain's TokenCTR provider is coming in the next release, and this is how it is built to work.

Free by default

With nothing set, builds stay on the offline build and the free routes. A build never creates a TokenCTR key on its own.

Paid only if you opt in

TokenCTR joins only when TOKENCTR_API_KEY is set and SC_TOKENCTR_PAID=1 is set, and then only with --provider tokenctr or --allow-paid.

Your own credits

Calls go through the TokenCTR gateway at api.tokenctr.com and draw on credits you bought.

Honest costs

The ledger marks every call free or paid. A cost it cannot measure is logged as unknown, never as $0.

An empty balance

When credits run out, the build falls back to the no-key chain if SC_AI=on is set, or to the offline build.

Until the next release

In 0.1.0 the OpenWork slot accepts any endpoint that speaks the same chat format, and the ledger books its cost as zero, so read real spend on your provider's own usage page. Prices for TokenCTR credits are set by TokenCTR, not by SpiderCaster.