Modeler

Modeler Skill

This skill manages structured business models for the Pigment OSS system. A model is the shared source of truth consumed by Analyst and Planner agents.

All operations are executed via:

npx business_analyst_cli modeler <command> [options]

When to Use

Use this skill when the user wants to:

• Create a new business model (budget, forecast, headcount plan, etc.)
• View the current state of a model
• Update a specific metric value or assumption
• Simulate a what-if scenario without changing the model
• List all available models
• Delete a model permanently

Do NOT use this skill to run analysis on the data — that is the Analyst agent's role.

Operations

1. list — List all models

npx business_analyst_cli modeler list

Returns a JSON array of available models with their names and last-updated timestamps.

When to use: When the user asks what models exist, or before operating on a model to confirm it exists.

2. create — Create a new model

npx business_analyst_cli modeler create <model-name> \
  --dimensions "Q1 2026" "Q2 2026" "Q3 2026" "Q4 2026" \
  --metrics "Revenue:USD" "Costs:USD" "Headcount:FTE" \
  --assumptions '{"revenue_growth_rate": 0.10, "cost_ratio": 0.70}' \
  --data '{"Revenue": {"Q1 2026": 100000}, "Costs": {"Q1 2026": 70000}}'

Arguments:

• <model-name> — unique identifier (lowercase, hyphens allowed, e.g. q1-business-plan)
• --dimensions — one or more dimension labels (time periods, regions, products, etc.)
• --metrics — one or more Name:Unit pairs (e.g. Revenue:USD, Headcount:FTE)
• --assumptions — JSON object of named assumptions and their values
• --data — (optional) JSON object with initial data values per metric per dimension

Output: Model created: <name>

3. view — Display a model

npx business_analyst_cli modeler view <model-name>

Renders the model as an ASCII table with metrics as rows and dimensions as columns, followed by the assumptions block.

Output example:

Model: q1-business-plan
Updated: 2026-03-20T10:00:00Z

               | Q1 2026  | Q2 2026  | Q3 2026
Revenue (USD)  | 100,000  | 110,000  |    —
Costs (USD)    |  70,000  |  77,000  |    —
Headcount (FTE)|      10  |      11  |    —

Assumptions:
  revenue_growth_rate: 0.10
  cost_ratio: 0.70

4. update — Update model data or assumptions

npx business_analyst_cli modeler update <model-name> --patch '<json>'

The patch JSON supports two shapes:

Update a data point:

{ "data": { "Revenue": { "Q2 2026": 115000 } } }

Update assumptions:

{ "assumptions": { "cost_ratio": 0.65 } }

Update both:

{
  "data": { "Headcount": { "Q3 2026": 12 } },
  "assumptions": { "revenue_growth_rate": 0.12 }
}

Output: Summary of what changed, e.g.:

Model updated: q1-business-plan
  data.Revenue.Q2 2026: 110000 → 115000
  assumptions.cost_ratio: 0.70 → 0.65

5. delete — Delete a model

npx business_analyst_cli modeler delete <model-name>

Permanently removes the model file from disk.

When to use: When the user wants to discard a model entirely.

Output: Model deleted: <name>

6. simulate — Run a what-if scenario

npx business_analyst_cli modeler simulate <model-name> --scenario '<json>' [--save-as <new-name>]

Applies overrides in memory and shows a before/after comparison. By default does not write to disk. If --save-as is provided, persists the simulated model as a new model file that analyst and planner tools can then operate on.

Optional flags:

• --save-as <new-name> — Save the simulated model as a new, separate model file. The new model can then be analyzed with analyst-skill or planned with planner-skill. Clean up with modeler delete <new-name> when done.

Scenario JSON shapes:

Override assumptions:

{ "assumption_overrides": { "revenue_growth_rate": 0.20 } }

Override specific data points:

{ "data_overrides": { "Revenue": { "Q1 2026": 130000 } } }

Output: Before/after comparison for affected values:

Simulation: q1-business-plan
Scenario: revenue_growth_rate 0.10 → 0.20

               | Q1 2026 (before) | Q1 2026 (after) | Delta
Costs (USD)    |           70,000 |          91,000 | +30.0%

Model Storage

Models are stored as JSON files in the models/ directory at the root of the agent folder:

pig_agents/_data/<model-name>.json

The script resolves this path as ../_data/ relative to the _src/ folder.

Examples

User: "What models do I have?"

npx business_analyst_cli modeler list

User: "Create a Q1 2026 revenue plan with monthly dimensions"

npx business_analyst_cli modeler create q1-revenue-plan \
  --dimensions "Jan 2026" "Feb 2026" "Mar 2026" \
  --metrics "Revenue:USD" "Costs:USD" "Margin:%" \
  --assumptions '{"cost_ratio": 0.65}'

User: "Show me the q1-revenue-plan"

npx business_analyst_cli modeler view q1-revenue-plan

User: "Update February revenue to 95000"

npx business_analyst_cli modeler update q1-revenue-plan \
  --patch '{"data": {"Revenue": {"Feb 2026": 95000}}}'

User: "What happens if our cost ratio drops to 60%?"

npx business_analyst_cli modeler simulate q1-revenue-plan \
  --scenario '{"assumption_overrides": {"cost_ratio": 0.60}}'

User: "What if our growth rate jumps to 25%? Save it so I can analyze and plan on it."

npx business_analyst_cli modeler simulate q1-revenue-plan \
  --scenario '{"assumption_overrides":{"revenue_growth_rate":0.25}}' \
  --save-as q1-aggressive

npx tsx ../../_src/cli/analyst.ts summary q1-aggressive

npx tsx ../../_src/cli/planner.ts recommend q1-aggressive --goal "maximize growth"

npx business_analyst_cli modeler delete q1-aggressive

User: "Delete the q1-revenue-plan model"

npx business_analyst_cli modeler delete q1-revenue-plan