How karawash-projects/pyursa works
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: frame.py Lazy Frame · tools.py Tool Session · semantic.py LLM Operators · base.py Backend Registry
Components 19
Dataframe API
- Public API
src/pyursa/__init__.py - Lazy Frame
src/pyursa/frame.py - Expressions
src/pyursa/expr.py - Strict Types
src/pyursa/types.py
Plan Execution
- Logical Plan
src/pyursa/plan.py - Backend Registry
src/pyursa/backends/base.py - Polars Backend
src/pyursa/backends/polars_backend.py - DuckDB Backend
src/pyursa/backends/duckdb_backend.py - Arrow Results
src/pyursa/backends/base.py
Agent Capabilities
- Structured Errors
src/pyursa/errors.py - LLM Summaries
src/pyursa/summarize.py - PII Redaction
src/pyursa/redact.py - Tool Session
src/pyursa/tools.py - Expression Parser
src/pyursa/parse.py - MCP Server
src/pyursa/mcp_server.py
LLM Integrations
- LLM Operators
src/pyursa/semantic.py - Provider Clients
src/pyursa/providers.py
Other components
- Analyst or Agent
- LLM Providers
Connections 26
- Analyst or Agent → Public API: uses
README.md - Public API → Lazy Frame: exposes
src/pyursa/__init__.py - Public API → Expressions: exposes
src/pyursa/__init__.py - Lazy Frame → Expressions: accepts
src/pyursa/frame.py - Lazy Frame → Logical Plan: builds
src/pyursa/frame.py - Lazy Frame → Backend Registry: executes on
src/pyursa/frame.py - Logical Plan → Strict Types: validates schema
src/pyursa/plan.py - Backend Registry → Polars Backend: registers
src/pyursa/backends/__init__.py - Backend Registry → DuckDB Backend: registers
src/pyursa/backends/__init__.py - Backend Registry → Arrow Results: returns
src/pyursa/backends/base.py - Polars Backend → Arrow Results: produces
src/pyursa/backends/base.py - DuckDB Backend → Arrow Results: produces
src/pyursa/backends/base.py - Lazy Frame → LLM Summaries: describes via
src/pyursa/frame.py - LLM Summaries → PII Redaction: uses
src/pyursa/summarize.py - LLM Operators → PII Redaction: uses
src/pyursa/semantic.py - Lazy Frame → LLM Operators: adds operators
src/pyursa/semantic.py - LLM Operators → Logical Plan: splits execution
src/pyursa/semantic.py - LLM Operators → Provider Clients: uses clients
src/pyursa/semantic.py - Provider Clients → LLM Providers: sends requests
README.md - Analyst or Agent → MCP Server: connects
README.md - MCP Server → Tool Session: exposes tools
src/pyursa/mcp_server.py - Tool Session → Lazy Frame: operates on
src/pyursa/tools.py - Tool Session → Expression Parser: parses expressions
src/pyursa/tools.py - Tool Session → LLM Summaries: requests summaries
src/pyursa/tools.py - Tool Session → LLM Operators: configures operators
src/pyursa/tools.py - Arrow Results → Analyst or Agent: returns table
README.md