How typedef-ai/fenic works
Project Type and Purpose
• This is a library/framework (Python + Rust) for AI data pipelines built around a DataFrame API with first-class LLM support.
• Purpose: let end users write Python code to build DataFrame queries enriched by semantic operators, then execute them locally or in the cloud with batched LLM inference (OpenAI, Anthropic, Google).
Main Architectural Components
A. Client Application (user code)
– Imports fenic, defines DataFrame pipelines (.filter(), .semantic.extract(), etc.)
B. Python Frontend/API Layer (src/fenic/api, src/fenic/core)
– Session management (session.py + config.py)
– DataFrame & logical plan builder (logical expressions + optimizer)
– Semantic function APIs (semantic.extract, classify, join, etc.)
C. Planner & Optimizer (src/fenic/core/_logical_plan)
– Builds a logical plan from API calls
– Applies rewrite rules (merge filters, pushdowns, semantic rewrite)
D. Execution Backends
1. Local Execution Backend (src/fenic/_backends/local)
– Physical planner/transpiler: converts logical plan → executable plan
– Rust-powered operators via PyO3 (chunking, JSON, markdown conversion)
– Polars plugins for data frames and local semantic operators
– Batching & orchestration of inference calls
2. Cloud Execution Backend (src/fenic/_backends/cloud)
– Cloud session manager, catalog, engine config
– Remote workers or serverless functions to run physical plan
– Centralized job orchestration and state (session_state.py)
E. Inference Clients (src/fenic/_inference)
– OpenAI, Anthropic, Google (Gemini) wrappers
– Batch chat completions & embeddings with retry, rate-limit, token counting
F. External Services
– LLM Providers (OpenAI, Anthropic, Google)
– Optionally cloud storage/databases for catalog or model registry
G. Observability & Persistence
– Logging (src/fenic/logging.py)
– Metrics tracking (src/fenic/core/metrics.py)
– Schema/catalog storage (local or cloud)
Component Relationships & Data Flow
• User code → Python API Layer → Logical Plan
• Logical Plan → Planner/Optimizer → Physical Plan
• Physical Plan → Execution Backend (Local or Cloud)
• Execution Backend → Inference Clients (batch LLM calls) → LLM Providers
• Execution Backend → Local Rust library for non-LLM operations (chunking, markdown)
• Backends report status, logs & metrics back to the user or monitoring system
Architectural Patterns & Principles
– Layered (API → Logical → Physical → Execution)
– Plugin/Adapter pattern for multiple backends and inference providers
– Lazy evaluation & optimizer rules inspired by Spark
– Separation of concerns: planning vs. execution, local vs. cloud
– Batching for cost efficiency and throughput
• Clear component labels (e.g., “Logical Planner”, “Local Executor”)