alran 0.0.0-stage → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ALRAN_TOOLS_NOTICES.md +64 -0
- package/LICENSE +27 -0
- package/LICENSE-STATUS.md +21 -0
- package/NOTICE +6 -0
- package/README.md +289 -2
- package/THIRD_PARTY_NOTICES.md +113 -0
- package/alran-tools.js +3 -0
- package/assets/agents/_default/prompt-auto_classifier.md +185 -0
- package/assets/agents/_default/prompt-auto_classifier_extras.md +17 -0
- package/assets/agents/_default/prompt-base-all.md +133 -0
- package/assets/agents/_default/prompt-base-all.md.hbs +228 -0
- package/assets/agents/_default/prompt-base-windows.md +5 -0
- package/assets/agents/_default/prompt-base-windows.md.hbs +5 -0
- package/assets/agents/_default/prompt-base-worker.md +10 -0
- package/assets/agents/_default/prompt-base-worker.md.hbs +27 -0
- package/assets/agents/_default/prompt-compact.md +76 -0
- package/assets/agents/_default/prompt-compact_continue.md +9 -0
- package/assets/agents/_default/prompt-git.md +8 -0
- package/assets/agents/_default/prompt-goal.md +13 -0
- package/assets/agents/_default/prompt-session-branch.md +3 -0
- package/assets/agents/_default/prompt-session-branch.md.hbs +30 -0
- package/assets/agents/_default/prompt-session-root.md +3 -0
- package/assets/agents/_default/prompt-session-root.md.hbs +32 -0
- package/assets/agents/_default/prompt-title.md +11 -0
- package/assets/agents/_default/prompt-tool_agent.md +22 -0
- package/assets/agents/_migration/README.md +20 -0
- package/assets/agents/_migration/coder/PERSONA.md +11 -0
- package/assets/agents/_migration/coder/system-prompt.md.hbs +42 -0
- package/assets/agents/_migration/general/PERSONA.md +11 -0
- package/assets/agents/_migration/general/system-prompt.md.hbs +49 -0
- package/assets/agents/_v2/AGENT_CONTEXT.md.hbs +245 -0
- package/assets/agents/_v2/PTC_TOOL_CALLS.md.hbs +35 -0
- package/assets/agents/_v2/coding/SYSTEM.md.hbs +173 -0
- package/assets/agents/_v2/explore.md.hbs +38 -0
- package/assets/agents/_v2/tui/SYSTEM.md.hbs +211 -0
- package/assets/agents/_v2/verifier.md.hbs +32 -0
- package/assets/agents/_v2/work/SYSTEM.md.hbs +186 -0
- package/assets/agents/_v2/worker.md.hbs +27 -0
- package/assets/agents/alran/PERSONA.md +7 -0
- package/assets/agents/alran/features/cron.md.hbs +0 -0
- package/assets/agents/alran/features/delegation.md.hbs +56 -0
- package/assets/agents/alran/features/memory.md.hbs +61 -0
- package/assets/agents/alran/features/recoverable-deletion.md.hbs +10 -0
- package/assets/agents/alran/features/task-management.md.hbs +11 -0
- package/assets/agents/alran/features/web-search.md.hbs +11 -0
- package/assets/agents/alran/modes/coding/online/PERSONA.md.hbs +20 -0
- package/assets/agents/alran/modes/coding/online/SYSTEM.md.hbs +158 -0
- package/assets/agents/alran/modes/work/online/PERSONA.md.hbs +20 -0
- package/assets/agents/alran/modes/work/online/SYSTEM.md.hbs +160 -0
- package/assets/agents/alran/prompt-session-root.md +4 -0
- package/assets/agents/alran/prompt-session-root.md.hbs +4 -0
- package/assets/agents/alran/skills/alran-code-product/SKILL.md +72 -0
- package/assets/agents/alran/skills/alran-code-product/references/account-models.md +61 -0
- package/assets/agents/alran/skills/alran-code-product/references/agents.md +34 -0
- package/assets/agents/alran/skills/alran-code-product/references/extensions.md +46 -0
- package/assets/agents/alran/skills/alran-code-product/references/workflows.md +56 -0
- package/assets/agents/alran/skills/control-in-app-browser/SKILL.md +590 -0
- package/assets/agents/alran/system-prompt.md.hbs +97 -0
- package/assets/agents/builtin-agents.json +1 -0
- package/assets/agents/desktop-task/archive-title/system-en.md +1 -0
- package/assets/agents/desktop-task/checkpoint/system.md +19 -0
- package/assets/agents/desktop-task/output-revision/system.md +1 -0
- package/assets/agents/desktop-task/retry/continuation.md +4 -0
- package/assets/agents/desktop-task/session-title/system.md +41 -0
- package/assets/agents/explore/PERSONA.md +8 -0
- package/assets/agents/explore/agent.md +14 -0
- package/assets/agents/explore/system-prompt.md.hbs +35 -0
- package/assets/agents/greeting.md +61 -0
- package/assets/agents/managed-prompts.json +47 -0
- package/assets/agents/prompt-exemptions.json +36 -0
- package/assets/agents/verifier/PERSONA.md +8 -0
- package/assets/agents/verifier/agent.md +17 -0
- package/assets/agents/verifier/system-prompt.md.hbs +28 -0
- package/assets/agents/worker/PERSONA.md +8 -0
- package/assets/agents/worker/agent.md +18 -0
- package/assets/agents/worker/system-prompt.md.hbs +22 -0
- package/assets/agents/workflow/code-review/review-candidates.md +120 -0
- package/assets/agents/workflow/code-review/reviewer-system.md +75 -0
- package/assets/agents/workflow/goal/budget-limit.md +16 -0
- package/assets/agents/workflow/goal/continuation.md +62 -0
- package/assets/agents/workflow/goal/objective-updated.md +16 -0
- package/assets/agents/workflow/goal/recovery-terminal-audit.md +13 -0
- package/assets/agents/workflow/goal/recovery.md +11 -0
- package/assets/agents/workflow/goal/terminal-audit.md +10 -0
- package/assets/agents/workflow/plan-mode/agent-entry.md +72 -0
- package/assets/agents/workflow/prompt-hook/system.md +0 -0
- package/assets/models-dev-catalog.json.gz +0 -0
- package/assets/prompts/code-review/review-candidates.md +120 -0
- package/assets/prompts/code-review/reviewer-system.md +75 -0
- package/assets/skills/alran-tools-master/SKILL.md +127 -0
- package/assets/skills/code-review/SKILL.md +51 -0
- package/assets/skills/cu-desktop/SKILL.md +255 -0
- package/assets/skills/deep-research/SKILL.md +30 -0
- package/assets/skills/deploy-website/SKILL.md +52 -0
- package/assets/skills/docx/LICENSE +21 -0
- package/assets/skills/docx/SKILL.md +259 -0
- package/assets/skills/docx/assets/styles/academic_styles.xml +250 -0
- package/assets/skills/docx/assets/styles/corporate_styles.xml +284 -0
- package/assets/skills/docx/assets/styles/default_styles.xml +449 -0
- package/assets/skills/docx/assets/xsd/aesthetic-rules.xsd +470 -0
- package/assets/skills/docx/assets/xsd/business-rules.xsd +130 -0
- package/assets/skills/docx/assets/xsd/common-types.xsd +159 -0
- package/assets/skills/docx/assets/xsd/wml-subset.xsd +589 -0
- package/assets/skills/docx/docs/acceptance-checklists/create.md +7 -0
- package/assets/skills/docx/docs/acceptance-checklists/edit.md +6 -0
- package/assets/skills/docx/docs/acceptance-checklists/layout-repair.md +7 -0
- package/assets/skills/docx/docs/acceptance-checklists/template.md +6 -0
- package/assets/skills/docx/docs/acceptance.md +139 -0
- package/assets/skills/docx/docs/anti-patterns.md +14 -0
- package/assets/skills/docx/docs/backends.md +116 -0
- package/assets/skills/docx/docs/evidence.md +73 -0
- package/assets/skills/docx/docs/failure-taxonomy.md +71 -0
- package/assets/skills/docx/docs/index.md +50 -0
- package/assets/skills/docx/docs/rendered-delivery.md +125 -0
- package/assets/skills/docx/docs/router.md +122 -0
- package/assets/skills/docx/docs/tables-and-numbering.md +27 -0
- package/assets/skills/docx/docs/task-apply-template.md +141 -0
- package/assets/skills/docx/docs/task-compare-two-docx.md +48 -0
- package/assets/skills/docx/docs/task-create.md +124 -0
- package/assets/skills/docx/docs/task-edit-fill.md +69 -0
- package/assets/skills/docx/docs/task-read-content.md +148 -0
- package/assets/skills/docx/docs/task-read-rendered.md +78 -0
- package/assets/skills/docx/docs/task-read-structure.md +93 -0
- package/assets/skills/docx/docs/task-repair-layout.md +70 -0
- package/assets/skills/docx/docs/template-dsl.md +32 -0
- package/assets/skills/docx/docs/track-changes.md +15 -0
- package/assets/skills/docx/docs/xml-patch-dsl.md +33 -0
- package/assets/skills/docx/references/cjk_typography.md +357 -0
- package/assets/skills/docx/references/cjk_university_template_guide.md +184 -0
- package/assets/skills/docx/references/comments_guide.md +191 -0
- package/assets/skills/docx/references/design_good_bad_examples.md +829 -0
- package/assets/skills/docx/references/design_principles.md +819 -0
- package/assets/skills/docx/references/openxml_element_order.md +308 -0
- package/assets/skills/docx/references/openxml_encyclopedia_part1.md +4061 -0
- package/assets/skills/docx/references/openxml_encyclopedia_part2.md +2820 -0
- package/assets/skills/docx/references/openxml_encyclopedia_part3.md +3381 -0
- package/assets/skills/docx/references/openxml_namespaces.md +82 -0
- package/assets/skills/docx/references/openxml_units.md +72 -0
- package/assets/skills/docx/references/sample-patch-plans.json +22 -0
- package/assets/skills/docx/references/sample-task-intents.json +5 -0
- package/assets/skills/docx/references/sample-template-manifests.json +21 -0
- package/assets/skills/docx/references/scenario_a_create.md +284 -0
- package/assets/skills/docx/references/scenario_b_edit_content.md +295 -0
- package/assets/skills/docx/references/scenario_c_apply_template.md +456 -0
- package/assets/skills/docx/references/track_changes_guide.md +200 -0
- package/assets/skills/docx/references/troubleshooting.md +506 -0
- package/assets/skills/docx/references/typography_guide.md +294 -0
- package/assets/skills/docx/references/xsd_validation_guide.md +158 -0
- package/assets/skills/docx/scripts/build_patch_plan.py +29 -0
- package/assets/skills/docx/scripts/diff_docx_structure.py +61 -0
- package/assets/skills/docx/scripts/doc_to_docx.ps1 +85 -0
- package/assets/skills/docx/scripts/doc_to_docx.sh +40 -0
- package/assets/skills/docx/scripts/docx_preview.ps1 +76 -0
- package/assets/skills/docx/scripts/docx_preview.sh +37 -0
- package/assets/skills/docx/scripts/docx_to_pdf.py +87 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/AlranAIDocx.Cli.csproj +19 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/Program.cs +18 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/AlranAIDocx.Core.csproj +15 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/AnalyzeCommand.cs +147 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ApplyTemplateCommand.cs +322 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/CreateCommand.cs +324 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/DiffCommand.cs +155 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/EditContentCommand.cs +487 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/FixOrderCommand.cs +108 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/MergeRunsCommand.cs +122 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ValidateCommand.cs +107 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/CommentSynchronizer.cs +169 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/ElementOrder.cs +80 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/NamespaceConstants.cs +42 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/RunMerger.cs +81 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/StyleAnalyzer.cs +81 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/TrackChangesHelper.cs +99 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/UnitConverter.cs +23 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples.cs +1832 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch1.cs +910 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch2.cs +999 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch3.cs +1048 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch4.cs +1038 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/CharacterFormattingSamples.cs +1020 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/DocumentCreationSamples.cs +1121 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FieldAndTocSamples.cs +624 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FootnoteAndCommentSamples.cs +675 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/HeaderFooterSamples.cs +838 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ImageSamples.cs +917 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ListAndNumberingSamples.cs +826 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ParagraphFormattingSamples.cs +1199 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/StyleSystemSamples.cs +1487 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TableSamples.cs +1163 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TrackChangesSamples.cs +595 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/CjkHelper.cs +39 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/FontDefaults.cs +24 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/PageSizes.cs +20 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/BusinessRuleValidator.cs +224 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/GateCheckValidator.cs +148 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/ValidationResult.cs +23 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/XsdValidator.cs +69 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.slnx +4 -0
- package/assets/skills/docx/scripts/env_check.ps1 +327 -0
- package/assets/skills/docx/scripts/env_check.sh +340 -0
- package/assets/skills/docx/scripts/extract_docx_text.py +1075 -0
- package/assets/skills/docx/scripts/pack_docx.py +31 -0
- package/assets/skills/docx/scripts/read_docx_structure.py +1032 -0
- package/assets/skills/docx/scripts/render_docx_pages.py +147 -0
- package/assets/skills/docx/scripts/rendered_report.py +609 -0
- package/assets/skills/docx/scripts/setup.ps1 +542 -0
- package/assets/skills/docx/scripts/setup.sh +537 -0
- package/assets/skills/docx/scripts/unpack_docx.py +29 -0
- package/assets/skills/docx/scripts/validate_template_manifest.py +60 -0
- package/assets/skills/docx/scripts/verify_anchor_atomicity.py +87 -0
- package/assets/skills/edit-deployed-website/SKILL.md +27 -0
- package/assets/skills/init/SKILL.md +135 -0
- package/assets/skills/llm-call/SKILL.md +48 -0
- package/assets/skills/llm-call/scripts/llm_call.py +458 -0
- package/assets/skills/pdf/SKILL.md +280 -0
- package/assets/skills/pdf/docs/advanced-reference.md +711 -0
- package/assets/skills/pdf/docs/create-guide.md +437 -0
- package/assets/skills/pdf/docs/design-guide.md +204 -0
- package/assets/skills/pdf/docs/forms-guide.md +462 -0
- package/assets/skills/pdf/docs/html-pdf-spec.md +500 -0
- package/assets/skills/pdf/docs/latex-academic-thesis-guide.md +233 -0
- package/assets/skills/pdf/docs/latex-technical-book-guide.md +112 -0
- package/assets/skills/pdf/docs/pitfalls-index.md +792 -0
- package/assets/skills/pdf/docs/read-guide.md +358 -0
- package/assets/skills/pdf/docs/reformat-guide.md +238 -0
- package/assets/skills/pdf/docs/skill-readme-archive.md +151 -0
- package/assets/skills/pdf/docs/troubleshooting.md +86 -0
- package/assets/skills/pdf/docs/vision-guide.md +188 -0
- package/assets/skills/pdf/scripts/__init__.py +0 -0
- package/assets/skills/pdf/scripts/_pdf_read_lib.py +284 -0
- package/assets/skills/pdf/scripts/fill/__init__.py +0 -0
- package/assets/skills/pdf/scripts/fill/acroform_apply.py +153 -0
- package/assets/skills/pdf/scripts/fill/overlay_apply.py +109 -0
- package/assets/skills/pdf/scripts/lib/__init__.py +0 -0
- package/assets/skills/pdf/scripts/lib/acroform_io.py +170 -0
- package/assets/skills/pdf/scripts/lib/cli_utils.py +41 -0
- package/assets/skills/pdf/scripts/lib/geometry.py +79 -0
- package/assets/skills/pdf/scripts/make.sh +388 -0
- package/assets/skills/pdf/scripts/merge.py +112 -0
- package/assets/skills/pdf/scripts/pdf_inspect/__init__.py +0 -0
- package/assets/skills/pdf/scripts/pdf_inspect/acroform_inspect.py +52 -0
- package/assets/skills/pdf/scripts/pdf_inspect/acroform_probe.py +57 -0
- package/assets/skills/pdf/scripts/pdf_inspect/layout_scan.py +164 -0
- package/assets/skills/pdf/scripts/read_pdf_vision.py +473 -0
- package/assets/skills/pdf/scripts/reformat_parse.py +181 -0
- package/assets/skills/pdf/scripts/render/__init__.py +0 -0
- package/assets/skills/pdf/scripts/render/overlay_preview.py +86 -0
- package/assets/skills/pdf/scripts/render/page_rasterize.py +85 -0
- package/assets/skills/pdf/scripts/render_html.cjs +205 -0
- package/assets/skills/pdf/scripts/validate/__init__.py +0 -0
- package/assets/skills/pdf/scripts/validate/geometry_lint.py +124 -0
- package/assets/skills/pdf/templates/INDEX.md +90 -0
- package/assets/skills/pdf/templates/bilingual-menu-premium/README.md +175 -0
- package/assets/skills/pdf/templates/bilingual-menu-premium/skeleton.html +343 -0
- package/assets/skills/pdf/templates/brand-guide-2page/README.md +140 -0
- package/assets/skills/pdf/templates/brand-guide-2page/skeleton.html +264 -0
- package/assets/skills/pdf/templates/data-viz-report/README.md +234 -0
- package/assets/skills/pdf/templates/data-viz-report/skeleton.html +835 -0
- package/assets/skills/pdf/templates/form-fill-acroform/README.md +195 -0
- package/assets/skills/pdf/templates/form-fill-acroform/field_values.template.json +118 -0
- package/assets/skills/pdf/templates/latex-academic-thesis/README.md +146 -0
- package/assets/skills/pdf/templates/latex-academic-thesis/source.tex +334 -0
- package/assets/skills/pdf/templates/latex-technical-book/README.md +130 -0
- package/assets/skills/pdf/templates/latex-technical-book/README.template-source.md +62 -0
- package/assets/skills/pdf/templates/latex-technical-book/source.tex +439 -0
- package/assets/skills/pdf/templates/multi-article-aggregator/README.md +148 -0
- package/assets/skills/pdf/templates/multi-article-aggregator/pipeline.md +223 -0
- package/assets/skills/pdf/templates/multilang-research-report/README.md +136 -0
- package/assets/skills/pdf/templates/multilang-research-report/skeleton.html +242 -0
- package/assets/skills/pdf/templates/reformat-default/README.md +136 -0
- package/assets/skills/pdf/templates/reformat-default/skeleton.html +204 -0
- package/assets/skills/pdf/templates/translate-preserve-layout/README.md +136 -0
- package/assets/skills/pdf/templates/translate-preserve-layout/skeleton.html +96 -0
- package/assets/skills/pdf/templates/translate-preserve-layout/terminology.template.json +66 -0
- package/assets/skills/pptx/SKILL.md +283 -0
- package/assets/skills/pptx/references/design-system.md +424 -0
- package/assets/skills/pptx/references/editing.md +162 -0
- package/assets/skills/pptx/references/element-map.md +229 -0
- package/assets/skills/pptx/references/pitfalls.md +205 -0
- package/assets/skills/pptx/references/pptxgenjs.md +420 -0
- package/assets/skills/pptx/references/preview-selection-writeback.md +65 -0
- package/assets/skills/pptx/references/python-pptx-recipes.md +63 -0
- package/assets/skills/pptx/references/slide-types.md +413 -0
- package/assets/skills/pptx/scripts/alran-ppt-map.cjs +280 -0
- package/assets/skills/pptx/scripts/audit_pptx.py +708 -0
- package/assets/skills/pptx/scripts/extract_comments.py +468 -0
- package/assets/skills/pptx/scripts/extract_images.py +226 -0
- package/assets/skills/pptx/scripts/extract_pptx.py +285 -0
- package/assets/skills/pptx/scripts/pdf2png.swift +203 -0
- package/assets/skills/pptx/scripts/pptx-screenshot.sh +105 -0
- package/assets/skills/resume-codex/SKILL.md +53 -0
- package/assets/skills/resume-codex/scripts/session-reader.mjs +445 -0
- package/assets/skills/skill-creator/SKILL.md +188 -0
- package/assets/skills/skill-creator/references/anti-patterns.md +149 -0
- package/assets/skills/skill-creator/references/commands-macos-linux.md +38 -0
- package/assets/skills/skill-creator/references/commands-windows-powershell.md +48 -0
- package/assets/skills/skill-creator/references/description-rubric.md +83 -0
- package/assets/skills/skill-creator/references/skill-template.md +101 -0
- package/assets/skills/skill-creator/references/when-to-bundle-scripts.md +139 -0
- package/assets/skills/skill-creator/scripts/lint-skill.js +226 -0
- package/assets/skills/skill-refiner/SKILL.md +137 -0
- package/assets/skills/visual-page/SKILL.md +194 -0
- package/assets/skills/x-link-reader/SKILL.md +108 -0
- package/assets/skills/xlsx/SKILL.md +498 -0
- package/assets/skills/xlsx/docs/advanced-reference.md +410 -0
- package/assets/skills/xlsx/docs/conventions-guide.md +217 -0
- package/assets/skills/xlsx/docs/create-edit-guide.md +410 -0
- package/assets/skills/xlsx/docs/pitfalls-index.md +759 -0
- package/assets/skills/xlsx/docs/raw-xml-escape-hatch.md +201 -0
- package/assets/skills/xlsx/docs/recalc-guide.md +295 -0
- package/assets/skills/xlsx/scripts/office/helpers/__init__.py +0 -0
- package/assets/skills/xlsx/scripts/office/helpers/merge_runs.py +199 -0
- package/assets/skills/xlsx/scripts/office/helpers/simplify_redlines.py +197 -0
- package/assets/skills/xlsx/scripts/office/pack.py +159 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd +1499 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd +146 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd +1085 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd +11 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd +3081 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd +23 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd +185 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd +287 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd +1676 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd +28 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd +144 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd +174 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd +25 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd +18 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd +59 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd +56 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd +195 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd +582 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd +25 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd +4439 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd +570 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd +509 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd +12 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd +108 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd +96 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd +3646 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd +116 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd +42 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd +50 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd +49 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd +33 -0
- package/assets/skills/xlsx/scripts/office/schemas/mce/mc.xsd +75 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2010.xsd +560 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2012.xsd +67 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2018.xsd +14 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cex-2018.xsd +20 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cid-2016.xsd +13 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd +4 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-symex-2015.xsd +8 -0
- package/assets/skills/xlsx/scripts/office/soffice.py +191 -0
- package/assets/skills/xlsx/scripts/office/unpack.py +132 -0
- package/assets/skills/xlsx/scripts/office/validate.py +117 -0
- package/assets/skills/xlsx/scripts/office/validators/__init__.py +15 -0
- package/assets/skills/xlsx/scripts/office/validators/base.py +851 -0
- package/assets/skills/xlsx/scripts/office/validators/docx.py +446 -0
- package/assets/skills/xlsx/scripts/office/validators/pptx.py +275 -0
- package/assets/skills/xlsx/scripts/office/validators/redlining.py +247 -0
- package/assets/skills/xlsx/scripts/recalc.py +450 -0
- package/chunks/account-commands-JZ6NXTTK.js +2 -0
- package/chunks/anthropic-MN33DP4E.js +2 -0
- package/chunks/application-ITGAJ4HC.js +2 -0
- package/chunks/auth-command-V3RVPLZO.js +2 -0
- package/chunks/azure-openai-responses-OWHMUNKC.js +2 -0
- package/chunks/chunk-2TF6JAQM.js +2 -0
- package/chunks/chunk-33CNY6GP.js +2 -0
- package/chunks/chunk-3AODGLMF.js +2 -0
- package/chunks/chunk-44VPC5LA.js +38 -0
- package/chunks/chunk-4CN3IJFH.js +2 -0
- package/chunks/chunk-4PDIO3M6.js +2 -0
- package/chunks/chunk-4X22UJQH.js +164 -0
- package/chunks/chunk-6255CZPL.js +2 -0
- package/chunks/chunk-6P4UKHGR.js +2 -0
- package/chunks/chunk-7QLAXRD2.js +1085 -0
- package/chunks/chunk-7XYOYZX2.js +2 -0
- package/chunks/chunk-A7GMJNA2.js +29 -0
- package/chunks/chunk-AGUSPIUP.js +2 -0
- package/chunks/chunk-BQ3CF3KE.js +2 -0
- package/chunks/chunk-C3CMJAAV.js +3 -0
- package/chunks/chunk-CJM7ZJ6W.js +7 -0
- package/chunks/chunk-CSOUJVKM.js +2 -0
- package/chunks/chunk-D66ZSHXR.js +2 -0
- package/chunks/chunk-D7MGU75P.js +2 -0
- package/chunks/chunk-E3GLGDGC.js +5 -0
- package/chunks/chunk-ENHOPPS7.js +16 -0
- package/chunks/chunk-EOR6EDNR.js +2 -0
- package/chunks/chunk-EYK25HWR.js +2 -0
- package/chunks/chunk-F46IELF5.js +2 -0
- package/chunks/chunk-FC4M2B7E.js +2 -0
- package/chunks/chunk-FSNYOJPJ.js +2 -0
- package/chunks/chunk-FUERW2DW.js +3 -0
- package/chunks/chunk-FXOH6TEQ.js +21 -0
- package/chunks/chunk-GP52JZMY.js +2 -0
- package/chunks/chunk-GRXX6I72.js +2 -0
- package/chunks/chunk-GSYHBK5Q.js +6 -0
- package/chunks/chunk-HNWBFJNO.js +2 -0
- package/chunks/chunk-IIE366LR.js +6706 -0
- package/chunks/chunk-IWK7PZP7.js +207 -0
- package/chunks/chunk-J3KCPYZT.js +2 -0
- package/chunks/chunk-KCLRJQ53.js +59 -0
- package/chunks/chunk-LU4RPLJ3.js +2 -0
- package/chunks/chunk-LZJYNT32.js +2 -0
- package/chunks/chunk-M7GW4VMR.js +27 -0
- package/chunks/chunk-MACBL5HF.js +2 -0
- package/chunks/chunk-N5NTXCJI.js +2 -0
- package/chunks/chunk-N5SVBCUB.js +7 -0
- package/chunks/chunk-N6W7ZL26.js +2 -0
- package/chunks/chunk-NWB7LFOK.js +131 -0
- package/chunks/chunk-OIQ336YE.js +16 -0
- package/chunks/chunk-OQNU3VPS.js +30 -0
- package/chunks/chunk-OTDNOWXG.js +16 -0
- package/chunks/chunk-PNXZWSWT.js +3 -0
- package/chunks/chunk-QFUV5PX6.js +2 -0
- package/chunks/chunk-QIN5ZBE2.js +2 -0
- package/chunks/chunk-QKBN5CGI.js +2 -0
- package/chunks/chunk-QPGTKSIQ.js +2 -0
- package/chunks/chunk-SIOLUFGG.js +2 -0
- package/chunks/chunk-TW23QKAD.js +3 -0
- package/chunks/chunk-U3RMPDXU.js +2 -0
- package/chunks/chunk-U7U3DJHF.js +2 -0
- package/chunks/chunk-VLXX22YO.js +2 -0
- package/chunks/chunk-WHD2XVT2.js +2 -0
- package/chunks/chunk-WTAJMYF2.js +249 -0
- package/chunks/chunk-WWNUAU4P.js +29 -0
- package/chunks/chunk-WYANV3IX.js +4 -0
- package/chunks/chunk-XAGZ6ZEU.js +9 -0
- package/chunks/chunk-XFCC2CI2.js +24 -0
- package/chunks/chunk-XQK7JM66.js +2 -0
- package/chunks/chunk-YLQXZBEL.js +2 -0
- package/chunks/chunk-YPV2X2RG.js +2 -0
- package/chunks/chunk-Z6BHCXKT.js +25 -0
- package/chunks/chunk-Z6HBNJCA.js +8 -0
- package/chunks/chunk-ZQKVUPKA.js +2 -0
- package/chunks/chunk-ZQOALVGL.js +2 -0
- package/chunks/clipboard-image-PQPC4EHR.js +2 -0
- package/chunks/data-dir-LDVKDCJ2.js +2 -0
- package/chunks/dist-2BRD4JFU.js +11 -0
- package/chunks/dist-EXKHRFQO.js +5 -0
- package/chunks/emscripten-module-RD6P2XH5.js +2 -0
- package/chunks/emscripten-module-WYNDFH3N.js +2 -0
- package/chunks/emscripten-module-XPTEOIWW.js +2 -0
- package/chunks/emscripten-module-ZS3PMSDF.js +2 -0
- package/chunks/ffi-IO7WZQNG.js +2 -0
- package/chunks/ffi-M5UP5J6C.js +2 -0
- package/chunks/ffi-ORLOPBB3.js +2 -0
- package/chunks/ffi-OUPK6AY6.js +2 -0
- package/chunks/google-UJAPMFAB.js +2 -0
- package/chunks/google-vertex-VLSF55PW.js +2 -0
- package/chunks/install-source-JTIUC4G4.js +2 -0
- package/chunks/launcher-FCZ3EDBF.js +61 -0
- package/chunks/lifecycle-GY435YMF.js +2 -0
- package/chunks/main-TQGGRHTS.js +13 -0
- package/chunks/mistral-ZJZUEF2X.js +3 -0
- package/chunks/module-6F3E5H7Y-BN7QWGYB.js +2 -0
- package/chunks/module-asyncify-R6PWJ6ZV-P4FWSBAY.js +2 -0
- package/chunks/multipart-parser-L6M455MS.js +2 -0
- package/chunks/network-proxy-U72JCK2I.js +2 -0
- package/chunks/openai-codex-responses-FPCDNRL5.js +2 -0
- package/chunks/openai-completions-D32YW6KL.js +2 -0
- package/chunks/openai-responses-ZCGSENM4.js +2 -0
- package/chunks/openrouter-G2EHY5BD.js +2 -0
- package/chunks/otel-OHXIZ666.js +2 -0
- package/chunks/package-contract-GVXTMJ3N.js +2 -0
- package/chunks/pdfjs-SHZAF7PF.js +107 -0
- package/chunks/photon_rs-C52RL4CI.js +3 -0
- package/chunks/plugin-command-OSAFHS7C.js +2 -0
- package/chunks/provider-command-SKTCHD4E.js +2 -0
- package/chunks/questionnaire-bridge-ISQOCYWY.js +2 -0
- package/chunks/run-acp-command-SG2BDMFJ.js +2 -0
- package/chunks/run-exec-command-5ADSQR2Z.js +15 -0
- package/chunks/skills-command-XXXEZAG6.js +2 -0
- package/chunks/src-DNIDEMVV.js +2 -0
- package/chunks/src-IBHIRTD7.js +2 -0
- package/chunks/telemetry-J7ZLGF5X.js +2 -0
- package/chunks/telemetry-command-COQG2AKK.js +5 -0
- package/chunks/tools-WDBB2JKV.js +2 -0
- package/chunks/undici-TUGHZJSA.js +2 -0
- package/chunks/update-NB6OD572.js +14 -0
- package/chunks/update-hint-ED7O67WU.js +3 -0
- package/chunks/wechat-onboard-UWXQW2HT.js +2 -0
- package/cli.js +5 -0
- package/configs/data-minimal.yaml +50 -0
- package/embedded/alran-tools/cli.mjs +4961 -0
- package/embedded/alran-tools/manifest.json +25 -0
- package/emscripten-module.wasm +0 -0
- package/image-preview-worker.js +2 -0
- package/internal-bin/alran-tools +9 -0
- package/internal-bin/alran-tools.cmd +8 -0
- package/matrix-mcp-stdio.js +4 -0
- package/native/darwin/prebuilds/darwin-arm64/darwin-modifiers.node +0 -0
- package/native/darwin/prebuilds/darwin-x64/darwin-modifiers.node +0 -0
- package/native/win32/prebuilds/win32-arm64/win32-console-mode.node +0 -0
- package/native/win32/prebuilds/win32-x64/win32-console-mode.node +0 -0
- package/package.json +38 -4
- package/photon_rs_bg.wasm +0 -0
- package/quickjs-worker.js +152 -0
- package/vendor/java-proxy-agent/build.ts +97 -0
- package/vendor/java-proxy-agent/srt-proxy-agent.jar +0 -0
- package/vendor/seccomp/arm64/apply-seccomp +0 -0
- package/vendor/seccomp/build.ts +74 -0
- package/vendor/seccomp/x64/apply-seccomp +0 -0
- package/vendor/srt-win/arm64/srt-win.exe +0 -0
- package/vendor/srt-win/build.ts +40 -0
- package/vendor/srt-win/x64/srt-win.exe +0 -0
|
@@ -0,0 +1,410 @@
|
|
|
1
|
+
# advanced-reference — situational xlsx libraries and workflows
|
|
2
|
+
|
|
3
|
+
> Material that is too situational for [`SKILL.md`](../SKILL.md) but worth
|
|
4
|
+
> documenting once: polars / duckdb / xlcalculator / pyexcel deep dives,
|
|
5
|
+
> the `extract-text` exploration CLI, large-file workflows, CI fallbacks,
|
|
6
|
+
> and the pandas → polars migration. Reach for this file when the default
|
|
7
|
+
> stack (pandas + openpyxl + `recalc.py`) does not fit the workload.
|
|
8
|
+
|
|
9
|
+
## 1. polars deep dive
|
|
10
|
+
|
|
11
|
+
`polars` is the right choice for any workbook above ~500k rows or any
|
|
12
|
+
pipeline where wall-clock latency matters. It uses Apache Arrow under
|
|
13
|
+
the hood and parses xlsx via `calamine`, which is roughly an order of
|
|
14
|
+
magnitude faster than openpyxl on read.
|
|
15
|
+
|
|
16
|
+
```python
|
|
17
|
+
import polars as pl
|
|
18
|
+
|
|
19
|
+
frame = pl.read_excel(
|
|
20
|
+
"mau_forecast.xlsx",
|
|
21
|
+
sheet_name="MAU_Forecast",
|
|
22
|
+
schema_overrides={
|
|
23
|
+
"Quarter": pl.Utf8,
|
|
24
|
+
"MAU (mm)": pl.Float64,
|
|
25
|
+
"Tokens (bn)": pl.Float64,
|
|
26
|
+
"ARR (¥mm)": pl.Float64,
|
|
27
|
+
},
|
|
28
|
+
has_header=True,
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
# Write back — note the limitations below
|
|
32
|
+
frame.write_excel("clean_mau.xlsx", worksheet="clean")
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
> ⚠️ **`write_excel` writes static numbers only** — no formulas, no
|
|
36
|
+
> charts, no styles, conditional formatting best-effort. Use it
|
|
37
|
+
> strictly for **raw data dumps** (a cleaned input frame, an exported
|
|
38
|
+
> query). The moment the deliverable contains derived values, switch to
|
|
39
|
+
> openpyxl on the write side and emit each derivation as `=` formulas.
|
|
40
|
+
> The large-file pattern in §6 shows the polars-read + openpyxl-write
|
|
41
|
+
> + `=SUMIF(...)` shape end-to-end.
|
|
42
|
+
|
|
43
|
+
`schema_overrides` is the polars equivalent of pandas's `dtype` kwarg
|
|
44
|
+
and is the recommended way to suppress column-by-column type-inference
|
|
45
|
+
surprises (the most common one is integer-like columns silently
|
|
46
|
+
becoming `Int64` and losing leading zeros).
|
|
47
|
+
|
|
48
|
+
`write_excel` limitations to know before reaching for it as a write
|
|
49
|
+
target:
|
|
50
|
+
|
|
51
|
+
- No formulas — every cell is a literal value
|
|
52
|
+
- No charts
|
|
53
|
+
- No styles (font, fill, border, alignment)
|
|
54
|
+
- Conditional formatting is best-effort and only on simple rules
|
|
55
|
+
|
|
56
|
+
For any output that needs formulas, styles, or charts, reach for
|
|
57
|
+
openpyxl on the write side and keep polars only for the read.
|
|
58
|
+
|
|
59
|
+
When to choose polars over pandas:
|
|
60
|
+
|
|
61
|
+
- File size > 500k rows, or > 500 MB on disk
|
|
62
|
+
- Memory pressure (containers with < 4 GB RAM, serverless functions)
|
|
63
|
+
- Pipeline already uses Arrow / DuckDB
|
|
64
|
+
- Lazy evaluation needed (`pl.scan_excel` is not yet supported, but
|
|
65
|
+
downstream operations on a polars frame can still fuse)
|
|
66
|
+
|
|
67
|
+
## 2. duckdb against xlsx
|
|
68
|
+
|
|
69
|
+
DuckDB can SQL-query an xlsx file directly via the spatial extension
|
|
70
|
+
(which understands GDAL's `OGR_XLSX` driver). Useful for joining
|
|
71
|
+
several sheets without writing a manual loop:
|
|
72
|
+
|
|
73
|
+
```sql
|
|
74
|
+
INSTALL spatial;
|
|
75
|
+
LOAD spatial;
|
|
76
|
+
|
|
77
|
+
-- Read a single sheet
|
|
78
|
+
SELECT * FROM st_read('model.xlsx', layer='Inputs') LIMIT 10;
|
|
79
|
+
|
|
80
|
+
-- Multi-sheet UNION (each layer becomes a table)
|
|
81
|
+
SELECT 'Inputs' AS source, * FROM st_read('model.xlsx', layer='Inputs')
|
|
82
|
+
UNION ALL
|
|
83
|
+
SELECT 'Outputs' AS source, * FROM st_read('model.xlsx', layer='Outputs');
|
|
84
|
+
|
|
85
|
+
-- Join two sheets on a shared key
|
|
86
|
+
SELECT i.cohort, i.users, o.arr
|
|
87
|
+
FROM st_read('model.xlsx', layer='Inputs') i
|
|
88
|
+
JOIN st_read('model.xlsx', layer='Outputs') o USING (cohort);
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Choose SQL over a DataFrame transform when the operation is naturally
|
|
92
|
+
relational (join across sheets, aggregate with `GROUP BY`, window
|
|
93
|
+
functions). DuckDB serializes the result back to a DataFrame in one
|
|
94
|
+
call (`con.execute(...).fetchdf()`) so the rest of the pipeline stays
|
|
95
|
+
familiar.
|
|
96
|
+
|
|
97
|
+
DuckDB read is nondestructive — formulas are evaluated on the cached
|
|
98
|
+
values present in the xlsx. Run `scripts/recalc.py` first if the file
|
|
99
|
+
has been edited but not yet recalculated.
|
|
100
|
+
|
|
101
|
+
## 3. xlcalculator — pure-Python recalculation
|
|
102
|
+
|
|
103
|
+
When LibreOffice cannot be installed (CI containers, serverless,
|
|
104
|
+
locked-down corporate machines),
|
|
105
|
+
[`xlcalculator`](https://github.com/bradbase/xlcalculator) is the
|
|
106
|
+
closest pure-Python equivalent.
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
pip install xlcalculator
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from xlcalculator import ModelCompiler, Evaluator
|
|
114
|
+
|
|
115
|
+
compiler = ModelCompiler()
|
|
116
|
+
model = compiler.read_and_parse_archive("model.xlsx")
|
|
117
|
+
evaluator = Evaluator(model)
|
|
118
|
+
print(evaluator.evaluate("MAU_Forecast!D2"))
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
The supported function list is maintained upstream
|
|
122
|
+
(<https://github.com/bradbase/xlcalculator#supported-functions>) — if a
|
|
123
|
+
formula uses anything outside that list, the evaluator raises
|
|
124
|
+
`UnsupportedFunctionError`. CI integration: wrap the call in
|
|
125
|
+
`try / except`, fall back to flagging the workbook for manual recalc.
|
|
126
|
+
|
|
127
|
+
Gaps to watch:
|
|
128
|
+
|
|
129
|
+
- Array formulas (`{=SUM(...)*...}`) and dynamic-array spill ranges
|
|
130
|
+
- Pivot tables (the cached values are returned but not recalculated)
|
|
131
|
+
- Custom functions (xlcalculator has no UDF support)
|
|
132
|
+
- Charts and conditional formatting (out of scope — calculator only)
|
|
133
|
+
|
|
134
|
+
## 4. pyexcel — format-agnostic recipes
|
|
135
|
+
|
|
136
|
+
`pyexcel` normalises csv / xlsx / ods / tsv into the same `[record_dict]`
|
|
137
|
+
or `[[row]]` structure. Use it when the input format is unknown ahead
|
|
138
|
+
of time, or when the pipeline accepts several formats and the consumer
|
|
139
|
+
does not care:
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
import pyexcel as pe
|
|
143
|
+
|
|
144
|
+
# Read whatever the file is, get list of dicts
|
|
145
|
+
records = pe.get_records(file_name="upload.xlsx")
|
|
146
|
+
records = pe.get_records(file_name="upload.csv")
|
|
147
|
+
records = pe.get_records(file_name="upload.ods")
|
|
148
|
+
|
|
149
|
+
# Convert csv to xlsx in one call
|
|
150
|
+
pe.save_book_as(file_name="raw.csv", dest_file_name="clean.xlsx")
|
|
151
|
+
pe.save_book_as(file_name="data.tsv", dest_file_name="data.ods")
|
|
152
|
+
|
|
153
|
+
# Multi-sheet workbook from a dict of lists
|
|
154
|
+
book = pe.Book({
|
|
155
|
+
"Inputs": [["k", "v"], ["growth", 0.05]],
|
|
156
|
+
"Outputs": [["q", "arr"], ["2025Q3", 148]],
|
|
157
|
+
})
|
|
158
|
+
book.save_as("model.xlsx")
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Useful glue for "user-uploaded spreadsheet, unknown extension" flows.
|
|
162
|
+
Drop back to pandas / openpyxl / polars when format is known and you
|
|
163
|
+
need richer control.
|
|
164
|
+
|
|
165
|
+
## 5. extract-text CLI — "look first, code second"
|
|
166
|
+
|
|
167
|
+
`extract-text` is the docx / pptx / xlsx companion CLI shared across
|
|
168
|
+
sibling skills. It dumps the workbook content to stdout, one
|
|
169
|
+
`## Sheet:` header per sheet, tab-separated cells per row:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
extract-text mau_forecast.xlsx | head -120
|
|
173
|
+
|
|
174
|
+
# .xlsm shares the .xlsx zip container — force the format if the
|
|
175
|
+
# extension confuses the auto-detect:
|
|
176
|
+
extract-text --format xlsx macro_book.xlsm | head -120
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Use it whenever the next code-write decision depends on what the file
|
|
180
|
+
actually contains — header positions, sheet names, merged regions, the
|
|
181
|
+
shape of the Assumptions block. Skipping this step and writing
|
|
182
|
+
exploratory openpyxl code blind wastes more tokens than the dump costs.
|
|
183
|
+
|
|
184
|
+
## 6. Large-file workflow
|
|
185
|
+
|
|
186
|
+
For files above ~500k rows, the read side dominates. The recommended
|
|
187
|
+
pattern is **pandas or polars on the read/transform/QA side, then
|
|
188
|
+
openpyxl/xlsxwriter only at the output boundary**. Do not use openpyxl
|
|
189
|
+
`iter_rows()`/cell loops to inspect or transform the source data.
|
|
190
|
+
Aggregations in the delivered workbook must live as `=SUMIF(...)` formulas
|
|
191
|
+
(or pivots), not as pre-computed numbers from pandas/polars.
|
|
192
|
+
|
|
193
|
+
Default choice:
|
|
194
|
+
|
|
195
|
+
- Use **pandas** when the workbook fits comfortably in memory and the task is
|
|
196
|
+
ordinary cleaning/filtering/joining. It is the default for 500k+ row
|
|
197
|
+
tabular work because it is simpler and much faster than openpyxl row loops.
|
|
198
|
+
- Use **polars** when pandas is memory-bound, latency-sensitive, or the data
|
|
199
|
+
is Arrow/DuckDB-adjacent.
|
|
200
|
+
- Use **openpyxl** only to assemble the final workbook features pandas/polars
|
|
201
|
+
cannot express: formulas, styles, named ranges, charts, template edits, and
|
|
202
|
+
XML-compatible workbook structure.
|
|
203
|
+
|
|
204
|
+
> **❌ Never `df.sample(N)` / `df.head(N)` / per-category truncation
|
|
205
|
+
> before writing the raw sheet.** Down-sampling 400k rows to 100k
|
|
206
|
+
> "because openpyxl writes are slow" silently destroys every
|
|
207
|
+
> aggregation built on top — the pivot or `=SUMIF` summary will be
|
|
208
|
+
> off by ~75% and look entirely plausible. The pivot still functions,
|
|
209
|
+
> the recalc gate still passes, the workbook still opens cleanly.
|
|
210
|
+
> There is no error to catch — just a wrong number flowing into a
|
|
211
|
+
> downstream decision. **Write the full row count, even if it takes
|
|
212
|
+
> minutes.** If raw-write throughput is the actual bottleneck, switch
|
|
213
|
+
> the writer (§6.1), never the sample size.
|
|
214
|
+
|
|
215
|
+
```python
|
|
216
|
+
import polars as pl
|
|
217
|
+
from openpyxl import Workbook
|
|
218
|
+
from openpyxl.utils import get_column_letter
|
|
219
|
+
|
|
220
|
+
# Stream-read with polars (Arrow + calamine) — fast read, no formula support.
|
|
221
|
+
frame = pl.read_excel("big_input.xlsx")
|
|
222
|
+
|
|
223
|
+
# Write the FULL raw frame to a "Raw" sheet — never a sample. Sampling
|
|
224
|
+
# here breaks every downstream pivot / SUMIF without raising any error
|
|
225
|
+
# the recalc gate can detect.
|
|
226
|
+
book = Workbook()
|
|
227
|
+
raw = book.active
|
|
228
|
+
raw.title = "Raw"
|
|
229
|
+
raw.append(frame.columns) # header
|
|
230
|
+
for row in frame.iter_rows():
|
|
231
|
+
raw.append(list(row)) # ALL rows
|
|
232
|
+
|
|
233
|
+
# Aggregation sheet — every "total" is a live SUMIF formula referencing Raw.
|
|
234
|
+
# Edit a Raw row, recalc, and the totals move automatically.
|
|
235
|
+
summary = book.create_sheet("Summary")
|
|
236
|
+
summary.append(["Cohort", "ARR (¥mm)"])
|
|
237
|
+
last_row = raw.max_row # data ends here
|
|
238
|
+
cohorts = sorted(frame["cohort"].unique().to_list()) # only used as keys
|
|
239
|
+
for r_idx, cohort in enumerate(cohorts, start=2):
|
|
240
|
+
summary.cell(row=r_idx, column=1, value=cohort)
|
|
241
|
+
summary.cell(
|
|
242
|
+
row=r_idx, column=2,
|
|
243
|
+
value=f"=SUMIF(Raw!A2:A{last_row}, A{r_idx}, Raw!B2:B{last_row})",
|
|
244
|
+
)
|
|
245
|
+
|
|
246
|
+
book.save("filled_template.xlsx")
|
|
247
|
+
# subprocess: python scripts/recalc.py filled_template.xlsx
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
When to use:
|
|
251
|
+
|
|
252
|
+
- Input workbook > 500k rows or > 500 MB
|
|
253
|
+
- Target workbook needs formulas / styles / charts that polars cannot write
|
|
254
|
+
|
|
255
|
+
Caveats:
|
|
256
|
+
|
|
257
|
+
- Each library has its own type system; round-tripping through polars
|
|
258
|
+
can drop the cell's number format. Re-apply formats on the openpyxl
|
|
259
|
+
side.
|
|
260
|
+
- Formulas in the source workbook are read as their **cached values**
|
|
261
|
+
(polars cannot evaluate them); re-add the formulas explicitly on the
|
|
262
|
+
openpyxl side if they need to remain live.
|
|
263
|
+
- Always finish with `scripts/recalc.py` so the cached values in the
|
|
264
|
+
output reflect the freshly written formulas.
|
|
265
|
+
- The polars-aggregate-and-dump shortcut (`frame.group_by(...).sum()`
|
|
266
|
+
written back as `write_number`) ships static totals — see the
|
|
267
|
+
`=SUMIF` recipe above for the formula-preserving alternative.
|
|
268
|
+
|
|
269
|
+
### 6.1 Choosing the writer when 400k+ rows is too slow
|
|
270
|
+
|
|
271
|
+
The pattern above uses regular `Workbook()`; on a 400k-row raw sheet
|
|
272
|
+
it can take minutes. Three accelerated variants — pick by what the
|
|
273
|
+
output workbook still needs to do:
|
|
274
|
+
|
|
275
|
+
| Need | Writer | Why |
|
|
276
|
+
|---|---|---|
|
|
277
|
+
| Output is the terminal artefact (no later openpyxl edits) | `xlsxwriter` (SKILL.md §3.3) | Fastest writer; cannot be reopened with openpyxl for further edits. Formulas must be written via `write_formula(...)`. |
|
|
278
|
+
| Need to keep editing with openpyxl after the bulk write | `openpyxl.Workbook(write_only=True)` + `WriteOnlyCell` | Streams rows to disk; ~4× faster than the default writer. Can be reopened normally. Cannot use `cell()` random access during the bulk phase. |
|
|
279
|
+
| Output is small enough that openpyxl works but pivot / chart authoring is the slow part | Default `Workbook()` + chunked `append()` in batches of 10k–50k | Lets you interleave pivot / chart objects with row writes. |
|
|
280
|
+
|
|
281
|
+
All three keep the **full** raw row count — that is the invariant. The
|
|
282
|
+
choice is purely about how the bytes get to disk faster.
|
|
283
|
+
|
|
284
|
+
Worked write-only example (the most common production path — fast
|
|
285
|
+
write, still editable later):
|
|
286
|
+
|
|
287
|
+
```python
|
|
288
|
+
from openpyxl import Workbook
|
|
289
|
+
from openpyxl.cell import WriteOnlyCell
|
|
290
|
+
|
|
291
|
+
book = Workbook(write_only=True)
|
|
292
|
+
raw = book.create_sheet("Raw")
|
|
293
|
+
raw.append(list(frame.columns))
|
|
294
|
+
for row in frame.iter_rows():
|
|
295
|
+
raw.append([WriteOnlyCell(raw, value=v) for v in row])
|
|
296
|
+
book.save("filled_template.xlsx")
|
|
297
|
+
|
|
298
|
+
# Reopen with the regular reader to add pivots / formula-driven Summary
|
|
299
|
+
# sheet / charts; only the bulk write goes through write_only mode.
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### 6.2 Pivot tables vs `=SUMIF` for the summary, plus slicers
|
|
303
|
+
|
|
304
|
+
Both `=SUMIF` and pivot tables belong to the formula-first regime —
|
|
305
|
+
both refresh when the raw data changes. Choose by structure complexity:
|
|
306
|
+
|
|
307
|
+
| Structure | Pick | Why |
|
|
308
|
+
|---|---|---|
|
|
309
|
+
| Single-axis aggregation (one key column → one metric) | `=SUMIF` / `=COUNTIF` / `=AVERAGEIF` in openpyxl | Pure formula; no Excel-specific objects to round-trip; survives any reopen / save cycle. |
|
|
310
|
+
| Multi-axis cross-tab, multiple metrics per cell, drill-down with slicers | Pivot table | `=SUMIFS` matrices become unmaintainable past 2 axes; pivots also expose slicers / timelines for interactive filtering. |
|
|
311
|
+
|
|
312
|
+
> **openpyxl cannot create pivot tables or slicers from scratch.** It
|
|
313
|
+
> can preserve them if they already exist in a loaded workbook (via a
|
|
314
|
+
> clean load → save cycle), but it has no API to author the
|
|
315
|
+
> `xl/pivotTables/*.xml` + `xl/pivotCaches/*.xml` + (for slicers)
|
|
316
|
+
> `xl/slicers/*.xml` parts. Two production paths:
|
|
317
|
+
>
|
|
318
|
+
> **(a) Template inheritance (recommended).** Author a
|
|
319
|
+
> `template.xlsx` once in Excel or LibreOffice with the pivot table
|
|
320
|
+
> and slicers already built and pointed at a named range that *will*
|
|
321
|
+
> hold the data. Each run:
|
|
322
|
+
>
|
|
323
|
+
> ```python
|
|
324
|
+
> from openpyxl import load_workbook
|
|
325
|
+
> book = load_workbook("template.xlsx")
|
|
326
|
+
> raw = book["Raw"]
|
|
327
|
+
> # Clear any sample rows the template ships with, then write all rows
|
|
328
|
+
> for r_idx, row in enumerate(frame.iter_rows(), start=2):
|
|
329
|
+
> for c_idx, v in enumerate(row, start=1):
|
|
330
|
+
> raw.cell(row=r_idx, column=c_idx, value=v)
|
|
331
|
+
> book.save("output.xlsx")
|
|
332
|
+
> # subprocess: python scripts/recalc.py output.xlsx
|
|
333
|
+
> ```
|
|
334
|
+
>
|
|
335
|
+
> The pivot's `<cacheSource><worksheetSource>` keeps pointing at the
|
|
336
|
+
> named range, so `recalc.py` auto-refreshes both pivot and slicer.
|
|
337
|
+
>
|
|
338
|
+
> **(b) Surgical XML transplant from a known-good template.** When a
|
|
339
|
+
> pivot layout is generated programmatically, copy the four XML parts
|
|
340
|
+
> above out of a template into the target via
|
|
341
|
+
> `scripts/office/unpack.py` + `pack.py` (see
|
|
342
|
+
> [`raw-xml-escape-hatch.md`](raw-xml-escape-hatch.md) §1 + §3 for
|
|
343
|
+
> the recipe). Never hand-author these parts from a blank file — the
|
|
344
|
+
> GUID bindings between slicer cache, pivot cache, and pivot table are
|
|
345
|
+
> not tractable to write from scratch.
|
|
346
|
+
>
|
|
347
|
+
> **If the user explicitly asks for "a slicer in the workbook" and
|
|
348
|
+
> you have no template to inherit from, say so and ask the user to
|
|
349
|
+
> provide one** — do not silently downgrade to a `=SUMIF` summary
|
|
350
|
+
> without mentioning the slicer can't be created from openpyxl.
|
|
351
|
+
|
|
352
|
+
## 7. CI / serverless considerations
|
|
353
|
+
|
|
354
|
+
In a container without LibreOffice:
|
|
355
|
+
|
|
356
|
+
- `scripts/recalc.py` will exit non-zero with `"soffice: command not
|
|
357
|
+
found"` — wrap calls in a `try / except` and fall back to
|
|
358
|
+
`xlcalculator` (§3) for an approximate recalc.
|
|
359
|
+
- Pre-validate every input cheaply with `openpyxl.load_workbook(path,
|
|
360
|
+
read_only=True)` before mutating; corrupt files fail fast (~50 ms)
|
|
361
|
+
instead of after a multi-minute polars read.
|
|
362
|
+
- Cache the LibreOffice user profile between CI runs so the macro at
|
|
363
|
+
`~/.config/libreoffice/.../basic/Standard/Module1.xba` does not
|
|
364
|
+
reinstall each time (saves 5-10 s per job).
|
|
365
|
+
- For containerised LibreOffice, prefer the `linuxserver/libreoffice`
|
|
366
|
+
or `collabora/code` images over `apt install libreoffice`; the
|
|
367
|
+
`--headless` mode in older Debian builds segfaults on certain locales.
|
|
368
|
+
|
|
369
|
+
## 8. Migration: pandas → polars
|
|
370
|
+
|
|
371
|
+
When to switch:
|
|
372
|
+
|
|
373
|
+
- Pipeline latency is the bottleneck (read takes > 30 s with pandas)
|
|
374
|
+
- Memory is the bottleneck (DataFrame > half of available RAM)
|
|
375
|
+
- Downstream ops are columnar (group-by, joins, window functions) —
|
|
376
|
+
polars's lazy frames fuse them into a single pass
|
|
377
|
+
|
|
378
|
+
What breaks during the migration:
|
|
379
|
+
|
|
380
|
+
| pandas behavior | polars behavior | Action |
|
|
381
|
+
|---|---|---|
|
|
382
|
+
| `pd.NaT` for missing dates | polars uses `null` with explicit type | Use `pl.col("d").is_null()` instead of `pd.isna` |
|
|
383
|
+
| Auto-convert object columns to dates | polars never auto-converts | Pass `try_parse_dates=True` to `read_excel` or coerce explicitly |
|
|
384
|
+
| Datetime tz handled by `dt.tz_localize` | polars uses `dt.replace_time_zone` | Update tz-handling code |
|
|
385
|
+
| `dtype="float64"` permissive | polars rejects mixed-type columns at read | Use `schema_overrides={col: pl.Float64}` |
|
|
386
|
+
| `to_excel` writes formulas | polars `write_excel` does not | Switch to openpyxl on the write side (§6) |
|
|
387
|
+
|
|
388
|
+
Rule of thumb: keep both libraries available, default to pandas,
|
|
389
|
+
upgrade to polars when one of the trigger conditions above hits.
|
|
390
|
+
Round-trip with `frame.to_pandas()` / `pl.from_pandas(frame)` so the
|
|
391
|
+
rest of the codebase keeps using whichever it already knows.
|
|
392
|
+
|
|
393
|
+
## 9. Out-of-scope reminder
|
|
394
|
+
|
|
395
|
+
The helpers under `scripts/office/` are cross-format zip / XSD
|
|
396
|
+
utilities shared with the docx and pptx sibling skills:
|
|
397
|
+
|
|
398
|
+
- `office/pack.py` — zip a directory of XML parts into a docx / pptx /
|
|
399
|
+
xlsx container
|
|
400
|
+
- `office/unpack.py` — unzip a docx / pptx / xlsx into editable XML
|
|
401
|
+
- `office/validate.py` — validate the XML parts against the
|
|
402
|
+
ECMA / W3C / Microsoft schemas under `office/schemas/`
|
|
403
|
+
|
|
404
|
+
These are not xlsx-specific creation tools — for xlsx output, stick to
|
|
405
|
+
openpyxl / xlsxwriter / polars / pyexcel as covered above.
|
|
406
|
+
|
|
407
|
+
**Do not edit `office/schemas/*.xsd`.** Those files are vendored copies
|
|
408
|
+
of the W3C / ECMA / ISO / Microsoft specifications. Regenerating or
|
|
409
|
+
hand-editing them silently breaks validation across docx, pptx, and
|
|
410
|
+
xlsx alike.
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# conventions-guide — financial-model conventions for Excel outputs
|
|
2
|
+
|
|
3
|
+
> The full rationale behind the tables in [`SKILL.md`](../SKILL.md) §5 —
|
|
4
|
+
> color coding, number formatting, hardcode source documentation, formula
|
|
5
|
+
> construction discipline, and template-preservation rules. Anything that
|
|
6
|
+
> reviewers would otherwise ask "why this and not that" goes here so the
|
|
7
|
+
> SKILL stays a quick scan and the deeper material is one click away.
|
|
8
|
+
|
|
9
|
+
## 1. Color coding
|
|
10
|
+
|
|
11
|
+
Default palette unless the user or the existing template overrides it.
|
|
12
|
+
Black is intentionally listed first: a reviewer scanning the workbook
|
|
13
|
+
should see one color signaling "this is computed", one signaling "this
|
|
14
|
+
is an input I can change", and three signaling links of increasing
|
|
15
|
+
risk. The anti-pattern column captures the way each color is most often
|
|
16
|
+
misused in the wild.
|
|
17
|
+
|
|
18
|
+
| Color | RGB | Meaning | Anti-pattern |
|
|
19
|
+
|---|---|---|---|
|
|
20
|
+
| Black | `0,0,0` | Every formula and computed result | Setting `=A1+B1` to blue makes the reviewer think it is a manual input |
|
|
21
|
+
| Blue | `0,0,255` | Hard-coded inputs and scenario assumptions | Setting `=Sheet2!A1` (a sheet link) to blue makes it look like an assumption |
|
|
22
|
+
| Green | `0,128,0` | Same-workbook cross-sheet links | Setting `=[Other.xlsx]Sheet1!A1` to green hides the external dependency signal |
|
|
23
|
+
| Red | `255,0,0` | Cross-file external links | Setting same-sheet `=A1` to red implies a fake external dependency |
|
|
24
|
+
| Yellow (fill) | `255,255,0` background | Critical assumptions awaiting review | Coloring every cell yellow drowns out the cells that actually need a second look |
|
|
25
|
+
|
|
26
|
+
Why "Black first": when a reviewer opens a model the first thing they
|
|
27
|
+
look for is whether any formula was accidentally typed as a number.
|
|
28
|
+
Putting black at the top of the legend mirrors that scan order.
|
|
29
|
+
|
|
30
|
+
## 2. Number formatting
|
|
31
|
+
|
|
32
|
+
Default formats unless the existing template specifies otherwise.
|
|
33
|
+
"Rationale" is what to point at when a reviewer asks why a column looks
|
|
34
|
+
the way it does.
|
|
35
|
+
|
|
36
|
+
| Type | Format | Rationale |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| Year | text (`"FY2025"`) | Numeric `2025` gets thousands-separated to `2,025` by the corporate template; storing as text disables the auto-format |
|
|
39
|
+
| Currency | `$#,##0` or `¥#,##0` with the unit (`mm` / `bn` / `k`) in the header | The unit belongs in one place per column, not repeated on every cell — header `ARR (¥mm)` keeps the cells uncluttered |
|
|
40
|
+
| Zero | `"$#,##0;($#,##0);-"` (or the `0.0%` equivalent) | A literal `0` reads as data; an em-dash reads as "zero by intent" — separates a missing value from a real zero |
|
|
41
|
+
| Percentage | `0.0%` | One decimal is enough for reviewer scanning; `0.00%` reads as false precision, `0%` loses sign on small movements |
|
|
42
|
+
| Multiple | `0.0x` | Used for valuation multiples (EV/EBITDA, P/S, P/E) and ratio-style headers like `Token unit price 1.2x` |
|
|
43
|
+
| Negative | `(123)` (parentheses) | Accounting convention; minus signs blend into table grids and read as dashes at small font sizes |
|
|
44
|
+
| Hardcode | `Source: …` annotation in the next column or as a cell comment (see §3) | Reviewer can audit every input back to its source without scrolling around |
|
|
45
|
+
|
|
46
|
+
Alran-flavored sample headers: `ARR (¥mm)` / `Tokens (bn)` / `MAU
|
|
47
|
+
(mm)` / `Token unit price 1.2x` / `MAU YoY 0.0%`. Keep the unit in the
|
|
48
|
+
header, not in the cell.
|
|
49
|
+
|
|
50
|
+
## 3. Hardcode `Source:` documentation
|
|
51
|
+
|
|
52
|
+
Every hard-coded number should carry its provenance — either as a cell
|
|
53
|
+
comment or as a string in the adjacent column. The grammar is fixed so
|
|
54
|
+
downstream automation can grep for it:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
Source: <system or document>, <date>, <locator>, <URL optional>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Five reference examples, spanning the source types reviewers see most:
|
|
61
|
+
|
|
62
|
+
| Source type | Example string |
|
|
63
|
+
|---|---|
|
|
64
|
+
| 10-K filing | `Source: AAPL 10-K FY2024, 2024-11-01, "Net sales by segment" table, https://www.sec.gov/...` |
|
|
65
|
+
| 10-Q filing | `Source: AAPL 10-Q FY2025 Q2, 2025-05-02, "Operating expenses" line 12` |
|
|
66
|
+
| Internal BI dashboard | `Source: Alran internal BI - MAU Dashboard, 2025-09-30, "moonshot-mau" view` |
|
|
67
|
+
| Interview transcript | `Source: User interview INT-2025-117, 2025-09-12, interviewee Z, page 4` |
|
|
68
|
+
| Market data terminal | `Source: Wind Terminal, 2025-08-15, AAPL.O closing price` / `Source: Bloomberg, 2025-08-15, AAPL US Equity PX_LAST` |
|
|
69
|
+
|
|
70
|
+
Date format is ISO `YYYY-MM-DD`; the locator must let a reader find the
|
|
71
|
+
exact cell in the source within ~30 seconds.
|
|
72
|
+
|
|
73
|
+
## 4. Formula construction rules
|
|
74
|
+
|
|
75
|
+
**The foundational rule: every computed value is a formula, not a
|
|
76
|
+
literal number.** Anything derivable from other cells — totals,
|
|
77
|
+
averages, ratios, percent changes, growth projections, lookups,
|
|
78
|
+
cross-sheet references — must be written as a live `=…` formula. Hard
|
|
79
|
+
numbers belong in §3 inputs only. Pasting a pre-computed total
|
|
80
|
+
(`125_430` instead of `=SUM(B2:B12)`) silently breaks the workbook
|
|
81
|
+
the moment any input cell changes; recalc cannot detect this because
|
|
82
|
+
the literal value evaluates fine — it just no longer reflects the
|
|
83
|
+
data. The four sub-rules below build on top of this principle and add
|
|
84
|
+
checks the model passes **before** running `scripts/recalc.py`.
|
|
85
|
+
recalc only catches errors that have already crystallised into a
|
|
86
|
+
`#REF!` / `#DIV/0!` marker; these checks catch the class of bugs that
|
|
87
|
+
produce a *wrong but not erroring* number.
|
|
88
|
+
|
|
89
|
+
**This rule applies regardless of how the value was computed during
|
|
90
|
+
authoring.** Even if pandas / polars / numpy / a one-line list
|
|
91
|
+
comprehension already produced the number in Python, the cell must
|
|
92
|
+
still hold the `=` formula referencing the source cells, not the
|
|
93
|
+
pre-computed result. The most common slip is loading raw data with
|
|
94
|
+
pandas, computing a derived column (`df["arr"] = df["mau"] *
|
|
95
|
+
df["price"]`), and writing the whole frame back with
|
|
96
|
+
`df.to_excel(...)`; that ships static numbers and undoes every
|
|
97
|
+
benefit of delivering a spreadsheet over a CSV. The right pattern is
|
|
98
|
+
to write only the **input columns** with pandas (or skip pandas
|
|
99
|
+
entirely and use openpyxl for everything), then emit each derived
|
|
100
|
+
column as `=B2*C2` etc. on the openpyxl side.
|
|
101
|
+
|
|
102
|
+
### 4.1 Assumption placement
|
|
103
|
+
|
|
104
|
+
All adjustable inputs live in a single dedicated **Assumptions** block
|
|
105
|
+
(usually a leading sheet or a clearly headlined region of the main
|
|
106
|
+
sheet). Downstream formulas reference these cells with `$`-locked
|
|
107
|
+
addresses so a fill-down does not silently skip them.
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
WRONG: =B5 * 1.05 // 5% growth hard-coded
|
|
111
|
+
RIGHT: =B5 * (1 + $B$6) // 5% growth lives in $B$6 (Assumptions)
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Sensitivity analysis (changing one assumption and watching the model
|
|
115
|
+
react) is impossible if the assumption is buried inside a formula.
|
|
116
|
+
|
|
117
|
+
### 4.2 Off-by-one sanity check
|
|
118
|
+
|
|
119
|
+
Every range in a `SUM`, `AVERAGE`, `COUNTIF`, etc. should be counted
|
|
120
|
+
literally. `SUM(B2:B12)` covers eleven rows (`12 - 2 + 1`), not ten.
|
|
121
|
+
The most common bug is summing only the first ten rows of an eleven-row
|
|
122
|
+
table because the model author counted the gap rather than the cells.
|
|
123
|
+
|
|
124
|
+
Quick check: open the formula bar, click into the range reference,
|
|
125
|
+
LibreOffice highlights the cells — confirm the highlight matches the
|
|
126
|
+
data block.
|
|
127
|
+
|
|
128
|
+
### 4.3 Boundary value testing
|
|
129
|
+
|
|
130
|
+
Before delivery, replace the lead inputs with edge cases and recalc:
|
|
131
|
+
|
|
132
|
+
| Input | Why test |
|
|
133
|
+
|---|---|
|
|
134
|
+
| `0` | Catches `#DIV/0!` and "any percentage of zero is still zero" semantics |
|
|
135
|
+
| Negative | Catches `LOG(<0)`, `SQRT(<0)`, and IRR convergence failures |
|
|
136
|
+
| Very large | Catches integer overflow in xlsxwriter and float underflow in `LOG10` chains |
|
|
137
|
+
| `NaN` (blank) | Catches `IFERROR` gaps and pandas → openpyxl conversion losses |
|
|
138
|
+
| Empty string | Catches `VALUE("")` failures and silent string concatenation |
|
|
139
|
+
|
|
140
|
+
Run `scripts/recalc.py` after each substitution. A real `errors_found`
|
|
141
|
+
JSON is the cheapest signal — far cheaper than a reviewer noticing a
|
|
142
|
+
silently-wrong percentile column three days later.
|
|
143
|
+
|
|
144
|
+
### 4.4 Circular reference avoidance
|
|
145
|
+
|
|
146
|
+
LibreOffice's `calculateAll()` fails loudly on circular references —
|
|
147
|
+
`recalc.py` will surface a `Circular reference detected` JSON before
|
|
148
|
+
ever returning a `total_formulas` count. Pre-check with openpyxl
|
|
149
|
+
before saving any model that wires inputs back into outputs:
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
from openpyxl import load_workbook
|
|
153
|
+
|
|
154
|
+
book = load_workbook("model.xlsx")
|
|
155
|
+
seen = set()
|
|
156
|
+
for sheet in book.worksheets:
|
|
157
|
+
for row in sheet.iter_rows():
|
|
158
|
+
for cell in row:
|
|
159
|
+
if isinstance(cell.value, str) and cell.value.startswith("="):
|
|
160
|
+
seen.add(f"{sheet.title}!{cell.coordinate}")
|
|
161
|
+
# Then walk references with a graph library (e.g. networkx) to find cycles.
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Iteration budget should always be the result of an explicit decision —
|
|
165
|
+
never leave "Iterative calculation" enabled by default.
|
|
166
|
+
|
|
167
|
+
## 5. Preserve existing templates
|
|
168
|
+
|
|
169
|
+
When updating someone else's template, **observe before edit**. Walk
|
|
170
|
+
the checklist below before changing a single cell:
|
|
171
|
+
|
|
172
|
+
- **Colors** — sample the current font / fill / border colors and
|
|
173
|
+
reuse the exact RGB triplets, even if they violate this skill's
|
|
174
|
+
defaults.
|
|
175
|
+
- **Column widths** — note the existing widths; resizing for "tidiness"
|
|
176
|
+
always breaks something downstream (a chart, a print layout, a
|
|
177
|
+
conditional format range).
|
|
178
|
+
- **Fonts** — if the template uses 宋体 / SimSun / a custom corporate
|
|
179
|
+
font, do not switch to Calibri.
|
|
180
|
+
- **Merged cells** — record every merged region before mutating the
|
|
181
|
+
sheet (see [`create-edit-guide.md`](create-edit-guide.md) §9).
|
|
182
|
+
- **Number formats** — copy the existing format string verbatim;
|
|
183
|
+
reformatting a cell will replace it.
|
|
184
|
+
- **Conditional formatting** — list the rules with `for cf in
|
|
185
|
+
sheet.conditional_formatting:` before editing the range; insertions
|
|
186
|
+
shift the rule's anchor.
|
|
187
|
+
|
|
188
|
+
Customer template conventions always override this skill's defaults.
|
|
189
|
+
|
|
190
|
+
## 6. Code style for Python operating Excel
|
|
191
|
+
|
|
192
|
+
These rules apply to the Python that drives openpyxl / xlsxwriter, not
|
|
193
|
+
to the Excel files themselves.
|
|
194
|
+
|
|
195
|
+
- **No tutorial comments.** Comments explain *why*, not *what* — the
|
|
196
|
+
reader knows what `book.save("foo.xlsx")` does.
|
|
197
|
+
- **No `print` debugging in committed code.** Use `logging.debug` or
|
|
198
|
+
return values; `print` lines pollute downstream stdout that callers
|
|
199
|
+
parse for JSON.
|
|
200
|
+
- **Business-named variables.** `book` / `sheet` / `frame` for the
|
|
201
|
+
workbook / worksheet / DataFrame. The terse `wb` / `ws` / `df`
|
|
202
|
+
reads as scratch-pad code; the full names match the financial-model
|
|
203
|
+
vocabulary the reviewer is already in.
|
|
204
|
+
- **List comprehensions over manual `for` accumulators** when the body
|
|
205
|
+
is a single expression — keeps the code at one screen.
|
|
206
|
+
|
|
207
|
+
## 7. Cell comment style
|
|
208
|
+
|
|
209
|
+
For the comments inside the workbook (right-click → Insert Comment):
|
|
210
|
+
|
|
211
|
+
- **Never use ALL CAPS.** Reviewers scanning the thumbnail interpret
|
|
212
|
+
all-caps as an error warning, even when the content is benign.
|
|
213
|
+
- **Font size 9–10 pt.** Smaller is unreadable on retina displays;
|
|
214
|
+
larger crops the comment box and looks shouty.
|
|
215
|
+
- **Cap at ~200 characters.** If the rationale is longer, link to a
|
|
216
|
+
shared doc or memo (`See: BI/MAU forecast methodology, 2025-09`)
|
|
217
|
+
rather than pasting the full text into the cell.
|