Skip to content

Installation

parsimony-agents is an AI agent framework for data analysis: it writes and executes Python code to answer questions about data. This page gets the package installed with the right optional extras for your use case and explains what each extra unlocks.

Requirements (Python 3.11 / 3.12)

The package declares requires-python = ">=3.11,<3.13", so you need Python 3.11 or 3.12. Python 3.10 and below, and Python 3.13 and above, are not supported.

Check your interpreter:

python --version
# Python 3.11.x  or  3.12.x

The parsimony-core dependency is installed automatically. It provides the connector model (parsimony.connector) and plugin discovery (parsimony.discover) used throughout the framework. The package metadata is the source of truth for the supported version range.

pip install parsimony-agents

The base install gives you the full agent loop, in-process code execution, charts (Altair / Vega-Lite), and the streaming event API. Hosts can opt into bubblewrap confinement by injecting the executor returned by create_executor:

pip install parsimony-agents

This pulls in the runtime dependencies declared in pyproject.toml — pandas, numpy, altair, litellm (the LLM gateway), and parsimony-core, among others.

The main public API is imported from the top-level parsimony_agents package:

from parsimony_agents import Agent, AgentResult, stream_to_display
from parsimony_agents import Dataset, Chart, Report, Script

See the public API reference for the complete top-level import surface.

You also need an LLM provider key (for example ANTHROPIC_API_KEY) for the Agent to call a model. That is environment configuration, not an install step — see Configuration.

Optional extras: sql, display, documents, all

Several capabilities are gated behind optional extras so the base install stays lean. Install them with the standard pip install "parsimony-agents[extra]" syntax (quote the brackets in most shells):

Extra Pulls in Unlocks
sql duckdb In-kernel SQL over your data
display rich Polished terminal rendering via stream_to_display / display_result
documents pypdf, openpyxl, python-pptx Reading PDF, Excel, and PowerPoint files
all sql + display + documents Everything above in one install

To search a large output, a result is a kernel variable, so an agent searches a DataFrame in code with the core catalog (auto_catalog(df).search(...), BM25 — in base parsimony-core, no extra needed).

Examples:

# Just the rich terminal UI
pip install "parsimony-agents[display]"

# Document parsing
pip install "parsimony-agents[documents]"

# Everything (sql + display + documents)
pip install "parsimony-agents[all]"

display — required for rich terminal output

stream_to_display (and display_result) render a live spinner, numbered tool progress, streamed text, dataset tables, and syntax-highlighted code. That polished rendering is powered by rich, which only ships with the display extra. The canonical quickstart uses it:

import asyncio
import os

from parsimony_fred import CONNECTORS as FRED

from parsimony_agents import Agent, stream_to_display


async def main() -> None:
    fred_key = os.environ.get("FRED_API_KEY")
    if not fred_key:
        print("Set FRED_API_KEY environment variable to run this example.")
        print("Get a free key at: https://fred.stlouisfed.org/docs/api/api_key.html")
        return

    agent = Agent(
        model="claude-sonnet-4-6",
        connectors=FRED.bind(api_key=fred_key),
    )

    # Ask a question — full display with progress and returned artifacts
    result = await stream_to_display(
        agent,
        "What is the current US unemployment rate? Fetch the data and show me.",
    )

    # Follow-up (multi-turn), reusing context
    await stream_to_display(
        agent,
        "Now show me how unemployment has changed since 2020",
        ctx=result.context,
    )


if __name__ == "__main__":
    asyncio.run(main())

If you do not install display, prefer the non-streaming Agent.ask or the raw Agent.run event generator — both work without rich. See Streaming and displaying results.

documents — required for PDF / Excel / PowerPoint inputs

The document readers the agent's kernel exposes — read_pdf_text, read_excel, and read_pptx_text — import their backing libraries at call time. With the base install those calls raise a RuntimeError telling you to install the documents extra:

  • read_pdf_text(path, max_pages=...) needs pypdf
  • read_excel(path, sheet_name=0, **kwargs) needs openpyxl
  • read_pptx_text(path) needs python-pptx

Install the extra to enable them:

pip install "parsimony-agents[documents]"

See SQL and document inputs for usage.

sql — DuckDB

The sql extra adds duckdb for running SQL inside the execution kernel. See SQL and document inputs.

Installing connectors (parsimony-fred, parsimony-sdmx, parsimony-fmp)

parsimony-agents ships no data connectors of its own. Connectors are separate packages that register against the parsimony.providers entry-point group; each one exports a CONNECTORS object (a parsimony.connector.Connectors collection).

Install the providers you need directly:

pip install parsimony-fred parsimony-sdmx parsimony-fmp

Each provider exposes a CONNECTORS constant you bind your API key onto:

from parsimony_fred import CONNECTORS as FRED
from parsimony_sdmx import CONNECTORS as SDMX
from parsimony_fmp import CONNECTORS as FMP

# Fix the api_key parameter across every connector that accepts it
fred = FRED.bind(api_key="your-fred-key")
fmp = FMP.bind(api_key="your-fmp-key")

# Compose collections with the + operator
combined = fred + fmp

Alternatively, discover every installed provider at once with parsimony.discover — no explicit imports needed:

from parsimony import discover

connectors = discover.load_all()   # forgiving: logs and skips load failures
# or, strict — raises if a name is not installed:
connectors = discover.load("fred", "fmp")

Tip: the framework's [examples] extra (pip install "parsimony-agents[examples]") bundles parsimony-fred, parsimony-fmp, and python-dotenv. Install parsimony-sdmx separately for examples or experiments that use SDMX.

For the full connector model — binding, composition, and discovery — see Connectors.

Verifying the install

Confirm the interpreter and core import resolve:

python -c "import parsimony_agents; print('parsimony-agents OK')"

Check the top-level API symbols are importable:

from parsimony_agents import Agent, AgentResult, stream_to_display, Dataset, Chart, Script
print("imports OK")

Verify the display extra is present (only succeeds when rich is installed):

python -c "import rich; print('display extra OK')"

Verify the documents extra by exercising a reader's import guard — with the extra installed this prints nothing and exits cleanly; without it you get a clear RuntimeError pointing you back here:

python -c "import pypdf, openpyxl, pptx; print('documents extra OK')"

List the connectors visible to plugin discovery:

from parsimony import discover

for p in discover.iter_providers():
    print(p.name, p.version)

If iter_providers() prints fred, sdmx, and/or fmp, those connector packages are installed and ready to bind.

Running the source examples

The runnable examples live in the repository rather than the published wheel. Clone the source and install the example dependencies before invoking them:

git clone https://github.com/ockham-sh/parsimony-agents
cd parsimony-agents
uv sync --extra examples --extra display
export FRED_API_KEY="..."
export GEMINI_API_KEY="..."

uv run python -m examples.quickstart
uv run python -m examples.event_stream
uv run python -m examples.terminal_chat

Additional examples cover SNB and SEC EDGAR data. Their module docstrings list the connector packages and credentials they require. Because examples/ is not included in the built wheel, python -m examples.* works from a source checkout, not after a plain pip install.

Next steps