Skills

A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project’s documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.

Any agent — install with npx:

npx skills add https://teal-insights.github.io/excel-grapher/

Codex / OpenCode

Tell the agent:
Fetch the skill file at https://teal-insights.github.io/excel-grapher/skill.md and follow the instructions.

Manual — download the skill file:

curl -O https://teal-insights.github.io/excel-grapher/skill.md

Or browse the SKILL.md file.

SKILL.md

---
name: excel-grapher
description: >
  Build and analyze dependency graphs from Excel workbooks. Use when writing Python code that uses the excel_grapher package.
license: Proprietary
compatibility: Requires Python >=3.11.
---

# excel_grapher

Build and analyze dependency graphs from Excel workbooks

## Installation

```bash
pip install excel-grapher
```

## API overview

### Public Modules

Namespaced public API surfaces

- `exporter.GoogleSeriesDocstringRenderer`
- `exporter.NumpySeriesDocstringRenderer`
- `exporter.PlainSeriesDocstringRenderer`
- `exporter.RstSeriesDocstringRenderer`
- `exporter.CodeGenerator`
- `exporter.IdentityTransitCompression`
- `exporter.FieldDoc`
- `exporter.SeriesBindingDocstringContext`
- `exporter.SeriesBindingDocstringContract`
- `exporter.SeriesFunctionDoc`
- `exporter.BaseProjectionManifest`
- `exporter.CollapsedGroup`
- `exporter.CompositeProjectionManifest`
- `exporter.FormulaRewrite`
- `exporter.ProjectedNodeSnapshot`
- `exporter.ProjectionResult`
- `exporter.SeriesDocstringRenderCallable`
- `exporter.SeriesDocstringRenderer`
- `exporter.SeriesBindingDocstringCallback`
- `exporter.ProjectionManifest`
- `exporter.ProjectionStep`
- `exporter.WebVizLayoutPlugin`
- `exporter.resolve_series_docstring_renderer`
- `exporter.list_series_docstring_callbacks`
- `exporter.register_series_docstring_callback`
- `exporter.resolve_series_docstring_callback`
- `exporter.unregister_series_docstring_callback`
- `exporter.to_web_viz_payload`
- `exporter.apply_projection`
- `exporter.build_forwarding_projection_manifest`
- `exporter.register_projection_manifest`
- `exporter.resolve_projection_manifest`
- `exporter.unregister_projection_manifest`
- `exporter.list_web_viz_layouts`
- `exporter.register_web_viz_layout`
- `exporter.resolve_web_viz_layout`
- `exporter.unregister_web_viz_layout`
- `exporter.SeriesDocstringRendererName`
- `exporter.SeriesDocstringRendererSpec`
- `exporter.SeriesBindingDocstringCallbackSpec`
- `exporter.WebVizPayload`
- `exporter.LAYOUT_FORCEATLAS2`
- `exporter.LAYOUT_GRAPHVIZ_DOT`
- `exporter.LAYOUT_GRAPHVIZ_SFDP`
- `exporter.LAYOUT_MULTIPARTITE`
- `exporter.LAYOUT_SPRING`
- `exporter.LAYOUT_STRATIFIED_MULTIPARTITE`
- `exporter.WebVizLayoutSpec`
- `grapher.GreaterThanCell`
- `grapher.NotEqualCell`
- `grapher.RealBetween`
- `grapher.RealIntervalDomain`
- `grapher.EdgeProvenance`
- `grapher.DynamicRefConfig`
- `grapher.DynamicRefLimits`
- `grapher.DynamicRefTraceEvent`
- `grapher.FromWorkbook`
- `grapher.LightweightVizLocalEdges`
- `grapher.LightweightVizModule`
- `grapher.LightweightVizModuleEdge`
- `grapher.LightweightVizNodeColumns`
- `grapher.LightweightVizPayload`
- `grapher.LightweightVizStats`
- `grapher.LocalForceSubgraph`
- `grapher.CycleReport`
- `grapher.DependencyGraph`
- `grapher.And`
- `grapher.Compare`
- `grapher.GuardExpr`
- `grapher.Literal`
- `grapher.Not`
- `grapher.Or`
- `grapher.GuardCellRef`
- `grapher.Node`
- `grapher.WorkbookCalcSettings`
- `grapher.GraphReadView`
- `grapher.CacheValidationPolicy`
- `grapher.DependencyCause`
- `grapher.DynamicRefError`
- `grapher.CycleError`
- `grapher.ValidationResult`
- `grapher.normalize_blank_range_specs`
- `grapher.create_dependency_graph`
- `grapher.list_dynamic_ref_constraint_candidates`
- `grapher.build_graph_cache_meta`
- `grapher.build_graph_cache_meta_portable`
- `grapher.save_graph_cache`
- `grapher.try_load_graph_cache`
- `grapher.infer_dynamic_index_targets`
- `grapher.infer_dynamic_indirect_targets`
- `grapher.infer_dynamic_offset_targets`
- `grapher.trace_dynamic_refs`
- `grapher.select_local_force_subgraph`
- `grapher.select_path_induced_subgraph`
- `grapher.to_graphviz`
- `grapher.to_mermaid`
- `grapher.to_networkx`
- `grapher.write_lightweight_viz_data`
- `grapher.write_lightweight_viz_html`
- `grapher.write_web_viz_html`
- `grapher.format_cell_key`
- `grapher.needs_quoting`
- `grapher.get_calc_settings`
- `grapher.validate_graph`
- `grapher.GRAPH_CACHE_SCHEMA_VERSION`
- `grapher.DynamicRefTraceFn`
- `grapher.NodeHook`
- `grapher.NodeKey`
- `grapher.format_key`
- `series_bindings.GoogleSeriesDocstringRenderer`
- `series_bindings.NumpySeriesDocstringRenderer`
- `series_bindings.PlainSeriesDocstringRenderer`
- `series_bindings.RstSeriesDocstringRenderer`
- `series_bindings.ResolutionIssue`
- `series_bindings.FieldDoc`
- `series_bindings.SeriesBindingDocstringContext`
- `series_bindings.SeriesBindingDocstringContract`
- `series_bindings.SeriesFunctionDoc`
- `series_bindings.SeriesDocstringRenderCallable`
- `series_bindings.SeriesDocstringRenderer`
- `series_bindings.SeriesBindingDocstringCallback`
- `series_bindings.SeriesBindingsLoadError`
- `series_bindings.SeriesBindingsSchemaError`
- `series_bindings.InputSeries`
- `series_bindings.InputSeriesCell`
- `series_bindings.LeafResolution`
- `series_bindings.OutputSeries`
- `series_bindings.OutputSeriesCell`
- `series_bindings.ResolutionReport`
- `series_bindings.SeriesResolution`
- `series_bindings.ValidationIssue`
- `series_bindings.ValidationReport`
- `series_bindings.WorkbookSeriesBindings`
- `series_bindings.emit_series_bindings_block`
- `series_bindings.bindings_canonical_sha256`
- `series_bindings.emit_compute_function`
- `series_bindings.emit_computes_block`
- `series_bindings.generate_computes_module`
- `series_bindings.resolve_series_docstring_renderer`
- `series_bindings.list_series_docstring_callbacks`
- `series_bindings.register_series_docstring_callback`
- `series_bindings.resolve_series_docstring_callback`
- `series_bindings.unregister_series_docstring_callback`
- `series_bindings.derive_input_series`
- `series_bindings.load_series_bindings`
- `series_bindings.merge_series_binding_documents`
- `series_bindings.parse_bindings_file`
- `series_bindings.has_input_direction`
- `series_bindings.has_output_direction`
- `series_bindings.merge_series_entries`
- `series_bindings.normalize_bindings_document`
- `series_bindings.normalize_series_entry`
- `series_bindings.derive_output_series`
- `series_bindings.expand_data_range`
- `series_bindings.expand_data_range_for_graph`
- `series_bindings.resolve_series_binding`
- `series_bindings.resolve_series_bindings`
- `series_bindings.format_schema_errors`
- `series_bindings.validate_bindings_document`
- `series_bindings.emit_setter_function`
- `series_bindings.emit_setter_helpers`
- `series_bindings.emit_setters_block`
- `series_bindings.generate_setters_module`
- `series_bindings.validate_series_bindings`
- `series_bindings.is_bind_implemented`
- `series_bindings.is_layout_implemented`
- `series_bindings.SeriesDocstringRendererName`
- `series_bindings.SeriesDocstringRendererSpec`
- `series_bindings.SeriesBindingDocstringCallbackSpec`
- `series_bindings.Record`
- `series_bindings.Records`
- `series_bindings.Scalar`
- `series_bindings.ValidationLevel`
- `series_bindings.IMPLEMENTED_BIND_KINDS`
- `series_bindings.IMPLEMENTED_LAYOUTS`
- `series_bindings.PLANNED_BIND_KINDS`
- `series_bindings.PLANNED_LAYOUTS`
- `series_bindings.SUPPORTED_SCHEMA_VERSIONS`

### Exporter API

Export and extension APIs under excel_grapher.exporter

- `exporter.CodeGenerator`
- `exporter.IdentityTransitCompression`
- `exporter.ProjectionStep`
- `exporter.ProjectionResult`
- `exporter.ProjectionManifest`
- `exporter.BaseProjectionManifest`
- `exporter.CompositeProjectionManifest`
- `exporter.ProjectedNodeSnapshot`
- `exporter.FormulaRewrite`
- `exporter.CollapsedGroup`
- `exporter.apply_projection`
- `exporter.build_forwarding_projection_manifest`
- `exporter.register_projection_manifest`
- `exporter.resolve_projection_manifest`
- `exporter.unregister_projection_manifest`
- `exporter.WebVizPayload`
- `exporter.to_web_viz_payload`
- `exporter.LAYOUT_FORCEATLAS2`
- `exporter.LAYOUT_GRAPHVIZ_DOT`
- `exporter.LAYOUT_GRAPHVIZ_SFDP`
- `exporter.LAYOUT_MULTIPARTITE`
- `exporter.LAYOUT_SPRING`
- `exporter.LAYOUT_STRATIFIED_MULTIPARTITE`
- `exporter.WebVizLayoutPlugin`
- `exporter.WebVizLayoutSpec`
- `exporter.list_web_viz_layouts`
- `exporter.register_web_viz_layout`
- `exporter.resolve_web_viz_layout`
- `exporter.unregister_web_viz_layout`
- `exporter.FieldDoc`
- `exporter.GoogleSeriesDocstringRenderer`
- `exporter.NumpySeriesDocstringRenderer`
- `exporter.PlainSeriesDocstringRenderer`
- `exporter.RstSeriesDocstringRenderer`
- `exporter.SeriesDocstringRenderCallable`
- `exporter.SeriesDocstringRenderer`
- `exporter.SeriesDocstringRendererName`
- `exporter.SeriesDocstringRendererSpec`
- `exporter.SeriesBindingDocstringCallback`
- `exporter.SeriesBindingDocstringCallbackSpec`
- `exporter.SeriesBindingDocstringContext`
- `exporter.SeriesBindingDocstringContract`
- `exporter.SeriesFunctionDoc`
- `exporter.list_series_docstring_callbacks`
- `exporter.register_series_docstring_callback`
- `exporter.resolve_series_docstring_callback`
- `exporter.unregister_series_docstring_callback`
- `exporter.resolve_series_docstring_renderer`

### Grapher Namespaced API

Public grapher APIs available under excel_grapher.grapher

- `grapher.DependencyCause`
- `grapher.EdgeProvenance`
- `grapher.LightweightVizLocalEdges`
- `grapher.LightweightVizModule`
- `grapher.LightweightVizModuleEdge`
- `grapher.LightweightVizNodeColumns`
- `grapher.LightweightVizStats`
- `grapher.GRAPH_CACHE_SCHEMA_VERSION`
- `grapher.DynamicRefTraceFn`
- `grapher.GraphReadView`
- `grapher.NodeHook`
- `grapher.NodeKey`
- `grapher.infer_dynamic_index_targets`
- `grapher.infer_dynamic_indirect_targets`
- `grapher.infer_dynamic_offset_targets`

### Series Bindings API

Series binding manifest and codegen APIs

- `series_bindings.InputSeries`
- `series_bindings.InputSeriesCell`
- `series_bindings.OutputSeries`
- `series_bindings.OutputSeriesCell`
- `series_bindings.Record`
- `series_bindings.Records`
- `series_bindings.Scalar`
- `series_bindings.FieldDoc`
- `series_bindings.GoogleSeriesDocstringRenderer`
- `series_bindings.NumpySeriesDocstringRenderer`
- `series_bindings.PlainSeriesDocstringRenderer`
- `series_bindings.RstSeriesDocstringRenderer`
- `series_bindings.SeriesDocstringRenderCallable`
- `series_bindings.SeriesDocstringRenderer`
- `series_bindings.SeriesDocstringRendererName`
- `series_bindings.SeriesDocstringRendererSpec`
- `series_bindings.SeriesBindingDocstringCallback`
- `series_bindings.SeriesBindingDocstringCallbackSpec`
- `series_bindings.SeriesBindingDocstringContext`
- `series_bindings.SeriesBindingDocstringContract`
- `series_bindings.SeriesFunctionDoc`
- `series_bindings.LeafResolution`
- `series_bindings.ResolutionIssue`
- `series_bindings.ResolutionReport`
- `series_bindings.SeriesResolution`
- `series_bindings.ValidationIssue`
- `series_bindings.ValidationLevel`
- `series_bindings.ValidationReport`
- `series_bindings.WorkbookSeriesBindings`
- `series_bindings.IMPLEMENTED_BIND_KINDS`
- `series_bindings.IMPLEMENTED_LAYOUTS`
- `series_bindings.PLANNED_BIND_KINDS`
- `series_bindings.PLANNED_LAYOUTS`
- `series_bindings.SUPPORTED_SCHEMA_VERSIONS`
- `series_bindings.bindings_canonical_sha256`
- `series_bindings.derive_input_series`
- `series_bindings.derive_output_series`
- `series_bindings.emit_compute_function`
- `series_bindings.emit_computes_block`
- `series_bindings.emit_series_bindings_block`
- `series_bindings.emit_setter_function`
- `series_bindings.emit_setter_helpers`
- `series_bindings.emit_setters_block`
- `series_bindings.generate_computes_module`
- `series_bindings.generate_setters_module`
- `series_bindings.has_input_direction`
- `series_bindings.has_output_direction`
- `series_bindings.merge_series_entries`
- `series_bindings.normalize_bindings_document`
- `series_bindings.normalize_series_entry`
- `series_bindings.expand_data_range`
- `series_bindings.expand_data_range_for_graph`
- `series_bindings.format_schema_errors`
- `series_bindings.list_series_docstring_callbacks`
- `series_bindings.load_series_bindings`
- `series_bindings.merge_series_binding_documents`
- `series_bindings.parse_bindings_file`
- `series_bindings.register_series_docstring_callback`
- `series_bindings.resolve_series_docstring_callback`
- `series_bindings.unregister_series_docstring_callback`
- `series_bindings.resolve_series_binding`
- `series_bindings.resolve_series_bindings`
- `series_bindings.resolve_series_docstring_renderer`
- `series_bindings.validate_bindings_document`
- `series_bindings.validate_series_bindings`
- `series_bindings.is_bind_implemented`
- `series_bindings.is_layout_implemented`

### Classes

Main classes provided by the package

- `CodeGenerator`: Generates Python code from Excel formulas
- `ParseError`: Raised when a formula cannot be parsed into an AST

### CodeGenerator Methods

Methods for the CodeGenerator class

- `CodeGenerator.__enter__`
- `CodeGenerator.__exit__`
- `CodeGenerator.derive_input_series`
- `CodeGenerator.classify_leaf_nodes`
- `CodeGenerator.generate`
- `CodeGenerator.generate_modules`

### Dataclasses

Dataclass definitions

- `And`: Logical AND
- `Compare`: Comparison: left op right
- `CycleReport`: Result of cycle analysis
- `DependencyGraph`: DependencyGraph(_nodes: 'dict[NodeKey, Node]' = <factory>, _edges: 'dict[NodeKey, set[NodeKey]]' = <factory>, _reverse_edges: 'dict[NodeKey, set[NodeKey]]' = <factory>, _guards: 'dict[EdgeKey, GuardExpr]' = <factory>, _edge_extra: 'dict[EdgeKey, dict[str, Any]]' = <factory>, _hooks: 'list[NodeHook]' = <factory>, leaf_classification: 'dict[str, str] | None' = None, sheet_order: 'list[str] | None' = None, sheet_bounds: 'dict[str, tuple[int, int]] | None' = None, named_ranges: 'dict[str, tuple[str, str]] | None' = None, named_range_ranges: 'dict[str, tuple[str, str, str]] | None' = None)
- `DynamicRefConfig`: Configuration for resolving OFFSET/INDIRECT via constraint-based inference
- `DynamicRefLimits`: Tuneable safety limits for dynamic-reference inference
- `DynamicRefTraceEvent`: A single trace event emitted during dynamic-ref inference
- `ExcelRange`: ExcelRange(sheet: 'str', start_row: 'int', start_col: 'int', end_row: 'int', end_col: 'int')
- `FormulaEvaluator`: FormulaEvaluator(graph: 'DependencyGraph', auto_detect_changes: 'bool' = True, eager_invalidation: 'bool' = True, on_cell_evaluated: 'Callable[[str, CellValue], None] | None' = None, iterate_enabled: 'bool' = False, iterate_count: 'int' = 100, iterate_delta: 'float' = 0.001, blank_ranges: 'tuple[str, ...] | None' = None)
- `FromWorkbook`: Metadata marker: resolve domain from the current cached workbook value
- `GreaterThanCell`: Metadata marker: the annotated cell is always greater than another cell
- `GuardCellRef`: A cell reference used in a condition
- `GuardExpr`: Base type for conditional dependency guards
- `LightweightVizPayload`: LightweightVizPayload(version: 'int', core: 'LightweightVizCore', overlays: 'tuple[LightweightVizOverlay, ...]', annotations: 'Mapping[str, Any] | None' = None, viewer_hints: 'Mapping[str, Any] | None' = None)
- `Literal`: A literal value in a condition
- `LocalForceSubgraph`: LocalForceSubgraph(node_ids: 'tuple[int, ...]', edges_from: 'tuple[int, ...]', edges_to: 'tuple[int, ...]', edges_guarded: 'tuple[bool, ...]', is_module_scope: 'bool', truncated: 'bool')
- `Node`: Workbook cell in a dependency graph
- `Not`: Logical negation
- `NotEqualCell`: Metadata marker: the annotated cell is never equal to another cell
- `Or`: Logical OR
- `RealBetween`: Real-valued interval constraint for Annotated float types (not enumerable for dynamic refs)
- `RealIntervalDomain`: Closed real-valued interval metadata; not enumerable for dynamic-ref branching
- `WorkbookCalcSettings`: WorkbookCalcSettings(iterate_enabled: 'bool', iterate_count: 'int', iterate_delta: 'float')

### DependencyGraph Methods

Methods for the DependencyGraph class

- `DependencyGraph.add_node`
- `DependencyGraph.__contains__`
- `DependencyGraph.__iter__`
- `DependencyGraph.__len__`
- `DependencyGraph.keys`
- `DependencyGraph.add_edge`
- `DependencyGraph.get_node`
- `DependencyGraph.get_dependencies`
- `DependencyGraph.get_dependents`
- `DependencyGraph.get_edge_attrs`
- `DependencyGraph.get_edge_guard`
- `DependencyGraph.set_node_value`
- `DependencyGraph.set_node_metadata`
- `DependencyGraph.register_hook`
- `DependencyGraph.leaves`
- `DependencyGraph.formula_nodes`
- `DependencyGraph.leaf_node_items`
- `DependencyGraph.formula_keys`
- `DependencyGraph.leaf_keys`
- `DependencyGraph.target_keys`
- `DependencyGraph.roots`
- `DependencyGraph.cycle_report`
- `DependencyGraph.evaluation_order`
- `DependencyGraph.compress_identity_transits`
- `DependencyGraph.__getstate__`
- `DependencyGraph.__setstate__`

### Enumerations

Enumeration types

- `CacheValidationPolicy`
- `XlError`

### Exceptions

Exception classes

- `CycleError`: Raised when a cycle prevents computing evaluation order
- `DynamicRefError`: Raised when dynamic reference analysis cannot proceed
- `SeriesBindingsLoadError`: Raised when binding files cannot be parsed or merged
- `SeriesBindingsSchemaError`: Raised when a binding manifest fails JSON Schema validation

### Named Tuples

Named tuple definitions

- `ValidationResult`: ValidationResult(is_valid, in_graph_not_in_chain, in_chain_not_in_graph, messages)

### Typed Dicts

TypedDict definitions

- `ValidationReport`

### Functions

Utility functions

- `bindings_canonical_sha256`: SHA-256 hex digest of the canonical binding manifest
- `build_graph_cache_meta`
- `build_graph_cache_meta_portable`: Build expected cache metadata without access to the workbook file
- `create_dependency_graph`: Build a dependency graph starting from target cells
- `format_cell_key`: Format a (sheet, column_letters, row) triple into a canonical address
- `get_calc_settings`: Extract calculation settings from xl/workbook.xml
- `list_dynamic_ref_constraint_candidates`: Return sorted leaf cells missing dynamic-ref constraint entries
- `load_series_bindings`: Load a binding sidecar file or directory of shards
- `needs_quoting`: Return True if a sheet name must be wrapped in single quotes in a formula
- `normalize_blank_range_specs`: Normalize a sequence of sheet-qualified range strings
- `resolve_series_bindings`: Resolve all series in a binding manifest for the given direction
- `save_graph_cache`
- `select_local_force_subgraph`
- `select_path_induced_subgraph`: Return the induced subgraph over nodes lying on directed source->target paths
- `to_graphviz`
- `to_mermaid`
- `to_networkx`: Convert a dependency graph to a NetworkX DiGraph
- `to_web_viz_payload`: Build a web-visualization payload from a NetworkX DiGraph
- `trace_dynamic_refs`: Activate *callback* as the dynamic-ref tracer for the enclosed block
- `try_load_graph_cache`
- `validate_graph`
- `validate_series_bindings`: Validate binding manifests against an extracted dependency graph
- `write_lightweight_viz_data`
- `write_lightweight_viz_html`
- `write_web_viz_html`: Write a web visualization HTML bundle from a web-viz payload

### Constants

Module-level constants and data

- `format_key`: Format a sheet and A1 cell coordinate into a canonical address string

## Resources

- [Full documentation](https://teal-insights.github.io/excel-grapher/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/Teal-Insights/excel-grapher)