idfa-ops

IDFA Operations

Scripts for programmatic interaction with IDFA-compliant Excel financial models.

---

When to Use This Skill

Activate when the idfa-financial-architect methodology skill calls for model interaction:

• Writing assumptions — setting Named Range input values
• Reading results — retrieving calculated outputs after recalculation
• Inspecting structure — listing all Named Ranges, formulas, and dependencies
• Auditing compliance — checking all four IDFA guardrails
• Recalculating — triggering deterministic formula evaluation via LibreOffice

This skill provides the HOW. The methodology skill provides the WHAT.

---

Prerequisites

Dependency	Required	Purpose
Python 3.10+	Yes	Script runtime
uv	Yes	PEP 723 inline dependency resolution
LibreOffice	Yes (for recalc)	Deterministic formula evaluation
Anthropic xlsx skill	Recommended	Provides battle-tested recalc.py

Scripts use PEP 723 inline metadata — uv run handles dependency installation automatically. Zero manual pip install needed.

---

Operations Reference

Operation	Command	What It Does
Write assumption	uv run scripts/idfa_ops.py write <file> <name> <value>	Set a Named Range input value
Read result	uv run scripts/idfa_ops.py read <file> <name> [name2...]	Read Named Range value(s)
Inspect model	uv run scripts/idfa_ops.py inspect <file>	List all Named Ranges, values, formulas
Read formula	uv run scripts/idfa_ops.py formula <file> <name>	Return the formula text for a Named Range
Create Named Range	uv run scripts/idfa_ops.py create-range <file> <name> <sheet> <cell>	Create a new Named Range definition
Recalculate	uv run scripts/recalc_bridge.py <file>	Trigger LibreOffice deterministic recalculation
Audit compliance	uv run scripts/idfa_audit.py <file>	Check all four IDFA guardrails, return JSON report

All script paths are relative to this skill's directory (skills/idfa-ops/).

---

The Write-Recalculate-Read Pattern

The fundamental interaction pattern for IDFA model operations. The agent reasons about what values to set, but the spreadsheet engine performs all arithmetic.

# Step 1: Write assumption
uv run scripts/idfa_ops.py write model.xlsx Inp_Rev_Y1 12000000

# Step 2: Recalculate (LibreOffice evaluates all formulas)
uv run scripts/recalc_bridge.py model.xlsx

# Step 3: Read results
uv run scripts/idfa_ops.py read model.xlsx Gross_Profit_Y1 Gross_Profit_Y2 Gross_Profit_Y3

Step 1 writes the assumption to the Named Range. The value is stored but dependent formulas are not yet recalculated.

Step 2 triggers LibreOffice to evaluate every formula in the workbook deterministically. This is essential — openpyxl cannot evaluate formulas.

Step 3 reads the recalculated results. The values returned are the model's deterministic output, not the agent's estimate.

---

Composing with the xlsx Skill

When Anthropic's xlsx skill is also installed, recalc_bridge.py automatically delegates to the xlsx skill's recalc.py for LibreOffice-based formula evaluation. When only idfa-ops is installed, recalc_bridge.py runs its own LibreOffice macro.

The interface is identical either way — the agent calls the same command regardless of which recalculation backend is available.

---

Output Formats

All scripts output JSON to stdout for agent consumption.

Success example (read):

{
  "status": "ok",
  "values": { "Gross_Profit_Y1": 4000000, "Gross_Profit_Y2": 4510000 }
}

Success example (inspect):

{"status": "ok", "named_ranges": [...], "count": 16}

Error example:

{ "error": "Named Range not found: Bad_Name" }

Exit codes: 0 = success, 1 = Named Range not found, 2 = file/usage error.

---

Output Best Practices

Every task that modifies or analyses a model MUST produce a Markdown results file saved to the output directory. The xlsx file alone is insufficient — a text artifact is needed for review, grading, and audit trail.

For multi-step operations (what-if, goal-seeking, multi-write scenarios):

1. Document each step: what command was run, what was returned
2. Include a summary table with before/after values
3. State the methodology: "All values obtained via write-recalculate-read pattern" or "Computed via formula tracing (LibreOffice unavailable)"
4. Save as <task>_results.md alongside the modified xlsx

This is not optional — the results file IS the deliverable. The xlsx is the artifact that proves it.

---

Error Handling

Error	Exit Code	Agent Action
Named Range not found	1	Inspect model to find correct name
File not found	2	Verify path and retry
LibreOffice not installed	1	Warn user; read/write still work but recalc unavailable
Permission denied	2	Check if file is open in Excel

When LibreOffice is unavailable, the agent can still write assumptions and read cached values — but the Write-Recalculate-Read pattern cannot complete. The agent should inform the user that results may not reflect the latest assumptions.

---

Attribution

IDFA Operations is part of the IDFA Financial Architect plugin, developed by the Panaversity team (https://panaversity.org). Proprietary — see LICENSE.