# karawash-projects/pyursa architecture

> Architecture diagram of the GitHub repository karawash-projects/pyursa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karawash-projects/pyursa
- Repository: https://github.com/karawash-projects/pyursa

## Overview

pyursa is a lazy, engine-neutral dataframe library extended for agent workflows. Users build immutable frames with expressions, execute the resulting plan on Polars or DuckDB, and inspect or export results. Agent-facing capabilities add structured errors, history and lineage, token-budgeted summaries, LLM operators, and an MCP tool server. The graph captures documented flows and relationships visible in the supplied excerpts or source index; unsampled subsystem internals and uncertain links are omitted.

Main entry points: [`src/pyursa/frame.py`](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/frame.py) (Lazy Frame), [`src/pyursa/tools.py`](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/tools.py) (Tool Session), [`src/pyursa/semantic.py`](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/semantic.py) (LLM Operators), [`src/pyursa/backends/base.py`](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/backends/base.py) (Backend Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dataframe["Dataframe API"]
  node_api["Public API<br/>[__init__.py]"]
  node_frame["Lazy Frame<br/>[frame.py]"]
  node_expr["Expressions<br/>[expr.py]"]
  node_types["Strict Types<br/>[types.py]"]
end

subgraph group_execution["Plan Execution"]
  node_plan["Logical Plan<br/>[plan.py]"]
  node_backend_registry["Backend Registry<br/>[base.py]"]
  node_polars["Polars Backend<br/>[polars_backend.py]"]
  node_duckdb["DuckDB Backend<br/>[duckdb_backend.py]"]
  node_arrow_result["Arrow Results<br/>[base.py]"]
end

subgraph group_agent["Agent Capabilities"]
  node_errors["Structured Errors<br/>[errors.py]"]
  node_summaries["LLM Summaries<br/>[summarize.py]"]
  node_redaction["PII Redaction<br/>[redact.py]"]
  node_tool_session["Tool Session<br/>[tools.py]"]
  node_parser["Expression Parser<br/>[parse.py]"]
  node_mcp["MCP Server<br/>[mcp_server.py]"]
end

subgraph group_integrations["LLM Integrations"]
  node_semantic["LLM Operators<br/>[semantic.py]"]
  node_providers["Provider Clients<br/>[providers.py]"]
end

node_user(("Analyst or Agent"))
node_llm_service{{"LLM Providers"}}

node_user -->|"uses"| node_api
node_api -->|"exposes"| node_frame
node_api -->|"exposes"| node_expr
node_frame -->|"accepts"| node_expr
node_frame -->|"builds"| node_plan
node_frame -->|"executes on"| node_backend_registry
node_plan -->|"validates schema"| node_types
node_backend_registry -->|"registers"| node_polars
node_backend_registry -->|"registers"| node_duckdb
node_backend_registry -->|"returns"| node_arrow_result
node_polars -->|"produces"| node_arrow_result
node_duckdb -->|"produces"| node_arrow_result
node_frame -->|"describes via"| node_summaries
node_summaries -->|"uses"| node_redaction
node_semantic -->|"uses"| node_redaction
node_frame -->|"adds operators"| node_semantic
node_semantic -->|"splits execution"| node_plan
node_semantic -->|"uses clients"| node_providers
node_providers -->|"sends requests"| node_llm_service
node_user -->|"connects"| node_mcp
node_mcp -->|"exposes tools"| node_tool_session
node_tool_session -->|"operates on"| node_frame
node_tool_session -->|"parses expressions"| node_parser
node_tool_session -->|"requests summaries"| node_summaries
node_tool_session -->|"configures operators"| node_semantic
node_arrow_result -->|"returns table"| node_user

click node_api "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/__init__.py"
click node_frame "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/frame.py"
click node_expr "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/expr.py"
click node_types "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/types.py"
click node_plan "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/plan.py"
click node_backend_registry "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/backends/base.py"
click node_polars "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/backends/polars_backend.py"
click node_duckdb "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/backends/duckdb_backend.py"
click node_arrow_result "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/backends/base.py"
click node_errors "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/errors.py"
click node_summaries "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/summarize.py"
click node_redaction "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/redact.py"
click node_semantic "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/semantic.py"
click node_providers "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/providers.py"
click node_tool_session "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/tools.py"
click node_parser "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/parse.py"
click node_mcp "https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/mcp_server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_frame,node_expr,node_types toneBlue
class node_plan,node_backend_registry,node_polars,node_duckdb,node_arrow_result toneAmber
class node_errors,node_summaries,node_redaction,node_tool_session,node_parser,node_mcp toneMint
class node_semantic,node_providers toneRose
class node_user,node_llm_service toneIndigo
```

## Components

### Dataframe API

- [Public API](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/__init__.py): `src/pyursa/__init__.py`
- [Lazy Frame](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/frame.py): `src/pyursa/frame.py`
- [Expressions](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/expr.py): `src/pyursa/expr.py`
- [Strict Types](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/types.py): `src/pyursa/types.py`

### Plan Execution

- [Logical Plan](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/plan.py): `src/pyursa/plan.py`
- [Backend Registry](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/backends/base.py): `src/pyursa/backends/base.py`
- [Polars Backend](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/backends/polars_backend.py): `src/pyursa/backends/polars_backend.py`
- [DuckDB Backend](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/backends/duckdb_backend.py): `src/pyursa/backends/duckdb_backend.py`
- [Arrow Results](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/backends/base.py): `src/pyursa/backends/base.py`

### Agent Capabilities

- [Structured Errors](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/errors.py): `src/pyursa/errors.py`
- [LLM Summaries](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/summarize.py): `src/pyursa/summarize.py`
- [PII Redaction](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/redact.py): `src/pyursa/redact.py`
- [Tool Session](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/tools.py): `src/pyursa/tools.py`
- [Expression Parser](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/parse.py): `src/pyursa/parse.py`
- [MCP Server](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/mcp_server.py): `src/pyursa/mcp_server.py`

### LLM Integrations

- [LLM Operators](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/semantic.py): `src/pyursa/semantic.py`
- [Provider Clients](https://github.com/karawash-projects/pyursa/blob/main/src/pyursa/providers.py): `src/pyursa/providers.py`

### Other components

- **Analyst or Agent**
- **LLM Providers**

## Connections

- Analyst or Agent → Public API: uses (evidence: `README.md`)
- Public API → Lazy Frame: exposes (evidence: `src/pyursa/__init__.py`)
- Public API → Expressions: exposes (evidence: `src/pyursa/__init__.py`)
- Lazy Frame → Expressions: accepts (evidence: `src/pyursa/frame.py`)
- Lazy Frame → Logical Plan: builds (evidence: `src/pyursa/frame.py`)
- Lazy Frame → Backend Registry: executes on (evidence: `src/pyursa/frame.py`)
- Logical Plan → Strict Types: validates schema (evidence: `src/pyursa/plan.py`)
- Backend Registry → Polars Backend: registers (evidence: `src/pyursa/backends/__init__.py`)
- Backend Registry → DuckDB Backend: registers (evidence: `src/pyursa/backends/__init__.py`)
- Backend Registry → Arrow Results: returns (evidence: `src/pyursa/backends/base.py`)
- Polars Backend → Arrow Results: produces (evidence: `src/pyursa/backends/base.py`)
- DuckDB Backend → Arrow Results: produces (evidence: `src/pyursa/backends/base.py`)
- Lazy Frame → LLM Summaries: describes via (evidence: `src/pyursa/frame.py`)
- LLM Summaries → PII Redaction: uses (evidence: `src/pyursa/summarize.py`)
- LLM Operators → PII Redaction: uses (evidence: `src/pyursa/semantic.py`)
- Lazy Frame → LLM Operators: adds operators (evidence: `src/pyursa/semantic.py`)
- LLM Operators → Logical Plan: splits execution (evidence: `src/pyursa/semantic.py`)
- LLM Operators → Provider Clients: uses clients (evidence: `src/pyursa/semantic.py`)
- Provider Clients → LLM Providers: sends requests (evidence: `README.md`)
- Analyst or Agent → MCP Server: connects (evidence: `README.md`)
- MCP Server → Tool Session: exposes tools (evidence: `src/pyursa/mcp_server.py`)
- Tool Session → Lazy Frame: operates on (evidence: `src/pyursa/tools.py`)
- Tool Session → Expression Parser: parses expressions (evidence: `src/pyursa/tools.py`)
- Tool Session → LLM Summaries: requests summaries (evidence: `src/pyursa/tools.py`)
- Tool Session → LLM Operators: configures operators (evidence: `src/pyursa/tools.py`)
- Arrow Results → Analyst or Agent: returns table (evidence: `README.md`)