Models — deterministic by default, any LLM optional¶

A model turns table metadata plus a plain-language objective into a design brief — which pages, which visuals, which filters, and the usage notes. pbigen ships two backends.

Privacy (applies to every provider below): only metadata — column names, canonical types and approximate distinct counts — is ever sent to a model. No row data leaves your machine. Every field the model returns is validated against the live schema; if the model is unreachable or returns something unusable, pbigen falls back to the deterministic design, so generation never hard-fails.

Deterministic (default) — no key, no network, no cost¶

Runs the rule-based, cardinality-aware design engine. This is what you get with no --model:

pbigen generate --source <kind> --set … --theme midnight --out out          # deterministic

pbigen.generate("<kind>", source_config={…})                                # deterministic
pbigen.generate("<kind>", source_config={…}, model="deterministic")         # explicit

Any LLM via LiteLLM — install once¶

pip install "pbigen[llm]"

pbigen uses LiteLLM, which speaks to ~100 providers with one interface. You pick the model with --model <id> (CLI) or model="<id>" (Python); credentials come from the provider's standard environment variables (or pass them explicitly — see the bottom).

Provider matrix¶

Provider	Install extra	Model id (`--model`)	Authenticate
OpenAI	`pbigen[llm]`	`gpt-4o-mini`, `gpt-4o`, `openai/o4-mini`	`export OPENAI_API_KEY=sk-…`
Anthropic	`pbigen[llm]`	`anthropic/claude-sonnet-4-6`, `anthropic/claude-3-5-haiku-latest`	`export ANTHROPIC_API_KEY=sk-ant-…`
Google — AI Studio	`pbigen[llm]`	`gemini/gemini-2.5-flash`, `gemini/gemini-2.5-pro`	`export GEMINI_API_KEY=…` (from aistudio.google.com/apikey)
Google — Vertex AI	`pbigen[llm]`	`vertex_ai/gemini-2.5-flash`	`gcloud auth application-default login` + `export VERTEXAI_PROJECT=… VERTEXAI_LOCATION=us-central1`
Azure OpenAI	`pbigen[llm]`	`azure/<your-deployment-name>`	`export AZURE_API_KEY=… AZURE_API_BASE=https://<res>.openai.azure.com/ AZURE_API_VERSION=2024-08-01-preview`
AWS Bedrock	`pbigen[llm]`	`bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0`	standard AWS creds (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` or a role) + `export AWS_REGION=us-east-1`
Ollama (local, open-source)	`pbigen[llm]`	`ollama/llama3`, `ollama/qwen2.5`	run `ollama serve`; endpoint `http://localhost:11434`
vLLM / LM Studio / any OpenAI-compatible	`pbigen[llm]`	`openai/<model>`	point `api_base` at your server; key can be a placeholder

LiteLLM supports far more (Mistral, Cohere, Groq, Together, OpenRouter, …) with the same pattern — --model <provider>/<model> + that provider's env var. See LiteLLM's provider docs for exact ids.

Examples¶

Hosted, key from the environment:

export OPENAI_API_KEY=sk-…
pbigen generate --source bigquery --set project=p dataset=d table=t \
  --model gpt-4o-mini --theme midnight --out out

export GEMINI_API_KEY=…
pbigen generate --source snowflake --set table=ORDERS database=ANALYTICS schema=SALES \
  --model gemini/gemini-2.5-flash --theme midnight --out out

Fully local, open-source (nothing leaves your network):

ollama serve &                      # in another shell: ollama pull llama3
pbigen generate --source parquet --set uri=./sales.parquet --model ollama/llama3 --out out

Python (set the endpoint via model_config):

pbigen.generate("parquet", source_config={"uri": "sales.parquet"},
                model="ollama/llama3",
                model_config={"api_base": "http://localhost:11434"})

Pass key/endpoint explicitly instead of env vars (Python):

pbigen.generate("bigquery", source_config={…},
                model="gpt-4o-mini",
                model_config={"api_key": "sk-…", "temperature": 0.2, "max_tokens": 12000})

How to tell the model actually ran¶

GenerateResult.model_name (Python) and the CLI summary report the backend used: deterministic vs. e.g. litellm:gpt-4o-mini. With a model, the generated pages/visuals differ from the deterministic run, and DESIGN.md lists each pipeline stage with its status. If no valid design came back (bad key, no network), the summary says deterministic (fallback — …).

Web research¶

--research web lets the research stage search the web and cite sources. It is used when the provider supports it through LiteLLM — OpenAI search models / GPT-5 (web_search_options), Anthropic Claude (the web-search tool) and Gemini (Google Search grounding). pbigen doctor --model <id> tells you whether it is available; otherwise the stage falls back to the built-in playbooks automatically and DESIGN.md records built-in knowledge (web unavailable).

Writing your own model¶

Subclass Model and return a Design. The easiest way is to reuse the staged pipeline with your own transport — any function that takes a system and a user prompt and returns JSON text:

from pbigen.ai.pipeline import DesignPipeline, DesignRequest
from pbigen.models.base import Model

class MyModel(Model):
    name = "my-model"
    def design(self, schema, objective, request=None):
        complete = lambda system, user, web=False: my_llm_call(system, user)
        return DesignPipeline(complete, self.name).run(schema, request or DesignRequest(objective))

pbigen.generate("bigquery", source_config={…}, model=MyModel())