API Reference¶

All public types are importable from indemnipy_ai.capabilities.excel.

from indemnipy_ai.capabilities.excel import (
    ExcelCapability,
    ExcelDeps,
    ExcelRuntimeState,
    DateParsingOptions,
    WorkbookProtocol,
    WorkbookTable,
    WorkbookSheet,
    VbaSummary,
)

ExcelCapability `dataclass` ¶

Bases: AbstractCapability[ExcelDeps | Any]

Gives an agent the ability to read and analyse spreadsheets.

Attach this capability to a pydantic-ai Agent to register a set of spreadsheet-reading tools and built-in workflow instructions. The agent can then load local .xlsx and .xlsm files, inspect worksheets and named tables, run DuckDB SQL queries, and store derived results that persist across turns.

When the agent runs, for_run checks whether the deps object implements ExcelDeps. If it does, the existing excel_runtime_state is reused so workbooks and derived tables from previous turns remain available. Otherwise a fresh ExcelRuntimeState is created for the run.

Attributes:

Name	Type	Description
`id`	`str \| None`	Capability identifier registered with the agent's toolset.
`runtime_state`	`ExcelRuntimeState`	Fallback state used when deps does not implement `ExcelDeps`.
`date_parsing_options`	`DateParsingOptions`	Controls how mixed-format or ambiguous date columns are coerced when loading workbook data.

for_run `async` ¶

for_run(ctx: RunContext[ExcelDeps | Any]) -> ExcelCapability

Prepare the capability for a run.

If deps implements ExcelDeps, the existing runtime state is reused so that workbooks and derived tables loaded in a previous turn are still available. Otherwise a fresh ExcelRuntimeState is created.

Parameters:

Name	Type	Description	Default
`ctx`	`RunContext[ExcelDeps \| Any]`	The run context.	required

get_description ¶

get_description() -> str | None

Get the description of the capability.

get_toolset ¶

get_toolset() -> FunctionToolset

Get the toolset for spreadsheet capabilities.

Returns:

Type	Description
`FunctionToolset`	The toolset containing spreadsheet-related tools.

ExcelDeps ¶

Bases: Protocol

Dependency protocol for spreadsheet capabilities.

Any object that has an excel_runtime_state attribute of type ExcelRuntimeState satisfies this protocol — no explicit inheritance is required.

Pass the same instance across multiple agent runs to preserve loaded workbooks and derived tables between turns in a multi-turn conversation.

Attributes:

Name	Type	Description
`excel_runtime_state`	`ExcelRuntimeState`	Mutable state holding loaded workbooks and derived tables.

ExcelRuntimeState `dataclass` ¶

Runtime state for ExcelCapability. Holds loaded workbooks and derived tables.

Pass the same instance across multiple agent runs to preserve loaded workbooks and derived tables between turns in a multi-turn conversation.

spreadsheets `class-attribute` `instance-attribute` ¶

spreadsheets: list[Path] = field(default_factory=list)

List of spreadsheets that have been loaded during the agent's execution.

workbooks `class-attribute` `instance-attribute` ¶

workbooks: dict[str, WorkbookProtocol] = field(default_factory=dict)

Mapping of file paths to loaded workbook instances.

derived_tables `class-attribute` `instance-attribute` ¶

derived_tables: dict[str, WorkbookTable] = field(default_factory=dict)

Mapping of derived table names to their corresponding WorkbookTable instances.

DateParsingOptions `dataclass` ¶

Options for parsing dates in spreadsheet data.

Attributes:

Name	Type	Description
`parse_dates`	`bool`	When `True`, strings that can be unambiguously parsed as dates are converted to `datetime` objects. Only applies to columns that already contain at least one date value.
`relaxed_about_day`	`bool`	When `True`, accepts strings where the day is missing or ambiguous, substituting the 1^st of the month. When `False` the day must be present and unambiguous.

VbaSummary `dataclass` ¶

Aggregates extracted VBA macros and heuristic analysis for one file.

Produced by WorkbookProtocol.vba_summary when macros are detected in a workbook. Use to_md to render the summary as a Markdown document suitable for passing to an agent.

Attributes:

Name	Type	Description
`filepath`	`Path`	Path to the workbook that was inspected.
`analysis_results`	`list[_VbaAnalysisResult]`	Heuristic findings returned by macro analysis (keyword type, keyword, and description).
`macros`	`list[_VbaMacro]`	Extracted VBA macro streams (filename, stream path, VBA filename, and source code).

from_file `classmethod` ¶

from_file(filepath: Path, parser: _VbaParser) -> VbaSummary

Build a summary from a workbook or OLE document.

Parameters:

Name	Type	Description	Default
`filepath`	`Path`	Path to the workbook to inspect.	required

Returns:

Type	Description
`VbaSummary`	A summary containing any detected analysis findings and extracted VBA macro streams.

to_md ¶

to_md() -> str

Render the summary as Markdown.

Returns:

Type	Description
`str`	A Markdown document containing analysis results followed by each extracted macro and its VBA source code.

WorkbookProtocol ¶

Bases: Protocol

Structural protocol for a loaded workbook.

Instances are created internally and stored in :attr:ExcelRuntimeState.workbooks <indemnipy_ai.capabilities.excel.ExcelRuntimeState.workbooks>. You will not normally construct these directly, but you can read them after a run to inspect what the agent loaded.

filepath `instance-attribute` ¶

filepath: Path

Path to the source file.

file_name `property` ¶

file_name: str

File name without directory path.

Returns:

Type	Description
`str`	The name of the workbook file as a string.

vba_summary `property` ¶

vba_summary: VbaSummary | None

VBA macro summary, or None if the workbook contains no macros.

Returns:

Type	Description
`VbaSummary \| None`	A `VbaSummary` instance if macros are present, otherwise `None`.

sheets `property` ¶

sheets: list[WorkbookSheet]

All worksheets in the workbook.

Returns:

Type	Description
`list[WorkbookSheet]`	A list of :class:`WorkbookSheet` instances.

get_range ¶

get_range(sheet_name: str, range_str: str) -> list[list[Any]]

Return raw cell values for a given range.

Parameters:

Name	Type	Description	Default
`sheet_name`	`str`	Name of the sheet to read from.	required
`range_str`	`str`	Range string, e.g. `"A1:C3"`.	required

Returns:

Type	Description
`list[list[Any]]`	A list of rows, each row being a list of cell values.

add_table_from_range ¶

add_table_from_range(sheet_name: str, range_str: str, table_name: str) -> None

Register a cell range as a named table on a sheet.

Parameters:

Name	Type	Description	Default
`sheet_name`	`str`	Name of the sheet containing the range.	required
`range_str`	`str`	Range string, e.g. `"A1:C3"`.	required
`table_name`	`str`	Name to assign to the new table. Must be unique within the sheet.	required

agent_summary ¶

agent_summary() -> str

Return a short text summary of the workbook's sheets and tables.

Returns:

Type	Description
`str`	A string suitable for passing to an agent as context.

WorkbookSheet `dataclass` ¶

Metadata for a single worksheet in a loaded workbook.

Returned via :attr:WorkbookProtocol.sheets. The tables list contains only named tables. Sheets with tabular data that has not been formally defined as a table will still appear here but with an empty tables list; use get_range to read their raw contents.

name `instance-attribute` ¶

name: str

The name of the sheet in the workbook.

range `instance-attribute` ¶

range: str

The full cell range occupied by the sheet, e.g. "A1:Z100".

freeze_panes `instance-attribute` ¶

freeze_panes: str | None

Freeze panes anchor cell, e.g. "B2", or None. Its presence may indicate tabular data even without a formally defined table.

min_column `instance-attribute` ¶

min_column: int

1-based index of the first used column.

min_row `instance-attribute` ¶

min_row: int

1-based index of the first used row.

max_column `instance-attribute` ¶

max_column: int

1-based index of the last used column.

max_row `instance-attribute` ¶

max_row: int

1-based index of the last used row.

state `instance-attribute` ¶

state: str

Visibility state of the sheet: 'visible' or 'hidden'.

tables `instance-attribute` ¶

tables: list[WorkbookTable]

Named tables defined on this sheet.

WorkbookTable `dataclass` ¶

A single table extracted from a workbook, or produced by a query.

Workbook tables come from named tables or ranges registered with add_table_from_range. Derived tables are created by query_store_and_preview and live in ExcelRuntimeState.derived_tables. For both types, the dataframe attribute; for those, sheet_name and range are empty strings.

name `instance-attribute` ¶

name: str

The name of the table as defined in the workbook.

sheet_name `instance-attribute` ¶

sheet_name: str

The name of the sheet where the table is located.

range `instance-attribute` ¶

range: str

The range of cells occupied by the table, e.g. "A1:C10".

dataframe `class-attribute` `instance-attribute` ¶

dataframe: DataFrame = field(repr=False)

The table's data as a Polars DataFrame.

API Reference¶

ExcelCapability dataclass ¶

for_run async ¶

get_description ¶

get_toolset ¶

ExcelDeps ¶

ExcelRuntimeState dataclass ¶

spreadsheets class-attribute instance-attribute ¶

workbooks class-attribute instance-attribute ¶

derived_tables class-attribute instance-attribute ¶

DateParsingOptions dataclass ¶

VbaSummary dataclass ¶

from_file classmethod ¶

to_md ¶

WorkbookProtocol ¶

filepath instance-attribute ¶

file_name property ¶

vba_summary property ¶

sheets property ¶

get_range ¶

add_table_from_range ¶

agent_summary ¶

WorkbookSheet dataclass ¶

name instance-attribute ¶

range instance-attribute ¶

freeze_panes instance-attribute ¶

min_column instance-attribute ¶

min_row instance-attribute ¶

max_column instance-attribute ¶

max_row instance-attribute ¶

state instance-attribute ¶

tables instance-attribute ¶

WorkbookTable dataclass ¶

name instance-attribute ¶

sheet_name instance-attribute ¶

range instance-attribute ¶

dataframe class-attribute instance-attribute ¶

ExcelCapability `dataclass` ¶

for_run `async` ¶

ExcelRuntimeState `dataclass` ¶

spreadsheets `class-attribute` `instance-attribute` ¶

workbooks `class-attribute` `instance-attribute` ¶

derived_tables `class-attribute` `instance-attribute` ¶

DateParsingOptions `dataclass` ¶

VbaSummary `dataclass` ¶

from_file `classmethod` ¶

filepath `instance-attribute` ¶

file_name `property` ¶

vba_summary `property` ¶

sheets `property` ¶

WorkbookSheet `dataclass` ¶

name `instance-attribute` ¶

range `instance-attribute` ¶

freeze_panes `instance-attribute` ¶

min_column `instance-attribute` ¶

min_row `instance-attribute` ¶

max_column `instance-attribute` ¶

max_row `instance-attribute` ¶

state `instance-attribute` ¶

tables `instance-attribute` ¶

WorkbookTable `dataclass` ¶

name `instance-attribute` ¶

sheet_name `instance-attribute` ¶

range `instance-attribute` ¶

dataframe `class-attribute` `instance-attribute` ¶