# typedef-ai/fenic architecture

> Architecture diagram of the GitHub repository typedef-ai/fenic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/typedef-ai/fenic
- Repository: https://github.com/typedef-ai/fenic

## Overview

##### 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”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    UserApp["Client Application\n(User Code)"]:::external

    %% Python Frontend/API Layer
    subgraph "Python Frontend/API Layer"
        direction TB
        SessionMgmt["Session Management"]:::pythonLayer
        DataFrameBuilder["DataFrame & Logical Plan Builder"]:::pythonLayer
        APICore["API Core Functions"]:::pythonLayer
    end

    %% Planner & Optimizer
    subgraph "Planner & Optimizer"
        direction TB
        LogicalPlans["Logical Plan Definitions"]:::pythonLayer
        Expressions["Expressions"]:::pythonLayer
        OptimizerRules["Optimizer Rules"]:::pythonLayer
    end

    %% Execution Backends
    subgraph "Execution Backends"
        direction TB
        subgraph "Local Execution Backend"
            direction TB
            LocalManager["Manager & Execution Driver"]:::pythonLayer
            PhysicalPlan["Physical Plan Transliteration"]:::pythonLayer
            subgraph "Rust Operators & Polars Plugins"
                direction TB
                RustOps["Rust Operators"]:::rust
                PolarsPlugins["Polars Plugins"]:::pythonLayer
            end
            LocalStorage["Local Session & Catalog Storage"]:::pythonLayer
        end
        subgraph "Cloud Execution Backend"
            direction TB
            CloudManager["Cloud Manager & Engine Config"]:::pythonLayer
            CloudCatalog["Catalog & Session State"]:::pythonLayer
            RemoteExec["Remote Execution Entry Point"]:::pythonLayer
        end
    end

    %% Inference Clients
    subgraph "Inference Clients"
        direction TB
        OpenAI["OpenAI Client"]:::external
        Anthropic["Anthropic Client"]:::external
        Google["Google (Gemini) Client"]:::external
        CommonOpenAI["Common OpenAI Core"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMProviders["LLM Providers\n(OpenAI, Anthropic, Google)"]:::external
    end

    %% Observability & Persistence
    subgraph "Observability & Persistence"
        direction TB
        Logging["Logging"]:::pythonLayer
        Metrics["Metrics Tracking"]:::pythonLayer
        SchemaSerde["Schema SerDe Utilities"]:::pythonLayer
    end

    %% Connections
    UserApp -->|"imports & defines pipelines"| SessionMgmt
    SessionMgmt -->|"builds queries"| DataFrameBuilder
    DataFrameBuilder -->|"calls core functions"| APICore
    APICore -->|"constructs logical plan"| LogicalPlans
    LogicalPlans -->|"uses expressions"| Expressions
    Expressions -->|"applies rules"| OptimizerRules
    OptimizerRules -->|"produces optimized plan"| LocalManager
    OptimizerRules -->|"produces optimized plan"| CloudManager

    LocalManager -->|"transpile →"| PhysicalPlan
    PhysicalPlan -->|"batch inference calls →"| RustOps
    PhysicalPlan -->|"use plugins →"| PolarsPlugins
    PhysicalPlan -->|"store state →"| LocalStorage

    CloudManager -->|"orchestrate →"| CloudCatalog
    CloudCatalog -->|"execute →"| RemoteExec

    LocalManager -->|"LLM batch call →"| OpenAI
    LocalManager -->|"LLM batch call →"| Anthropic
    LocalManager -->|"LLM batch call →"| Google

    RemoteExec -->|"LLM batch call →"| OpenAI
    RemoteExec -->|"LLM batch call →"| Anthropic
    RemoteExec -->|"LLM batch call →"| Google

    OpenAI -->|"API call"| LLMProviders
    Anthropic -->|"API call"| LLMProviders
    Google -->|"API call"| LLMProviders

    LocalManager -->|"logs & metrics"| Logging
    CloudManager -->|"logs & metrics"| Logging
    LocalManager -->|"metrics"| Metrics
    CloudManager -->|"metrics"| Metrics
    LocalManager -->|"schema storage"| SchemaSerde
    CloudCatalog -->|"schema storage"| SchemaSerde

    %% Click Events
    click UserApp "https://github.com/typedef-ai/fenic/tree/main/examples/"
    click SessionMgmt "https://github.com/typedef-ai/fenic/blob/main/src/fenic/api/session/session.py"
    click SessionMgmt "https://github.com/typedef-ai/fenic/blob/main/src/fenic/api/session/config.py"
    click DataFrameBuilder "https://github.com/typedef-ai/fenic/blob/main/src/fenic/api/dataframe/dataframe.py"
    click DataFrameBuilder "https://github.com/typedef-ai/fenic/blob/main/src/fenic/api/dataframe/semantic_extensions.py"
    click APICore "https://github.com/typedef-ai/fenic/blob/main/src/fenic/api/functions/semantic.py"
    click APICore "https://github.com/typedef-ai/fenic/blob/main/src/fenic/api/functions/core.py"
    click APICore "https://github.com/typedef-ai/fenic/blob/main/src/fenic/api/functions/builtin.py"
    click LogicalPlans "https://github.com/typedef-ai/fenic/tree/main/src/fenic/core/_logical_plan/plans/"
    click Expressions "https://github.com/typedef-ai/fenic/tree/main/src/fenic/core/_logical_plan/expressions/"
    click OptimizerRules "https://github.com/typedef-ai/fenic/tree/main/src/fenic/core/_logical_plan/optimizer/"
    click LocalManager "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_backends/local/manager.py"
    click PhysicalPlan "https://github.com/typedef-ai/fenic/tree/main/src/fenic/_backends/local/physical_plan/"
    click RustOps "https://github.com/typedef-ai/fenic/tree/main/rust/src/"
    click PolarsPlugins "https://github.com/typedef-ai/fenic/tree/main/src/fenic/_backends/local/polars_plugins/"
    click LocalStorage "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_backends/local/session_state.py"
    click LocalStorage "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_backends/local/schema_storage.py"
    click CloudManager "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_backends/cloud/manager.py"
    click CloudManager "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_backends/cloud/engine_config.py"
    click CloudCatalog "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_backends/cloud/catalog.py"
    click CloudCatalog "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_backends/cloud/session_state.py"
    click RemoteExec "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_backends/cloud/execution.py"
    click OpenAI "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_inference/openai/openai_batch_chat_completions_client.py"
    click OpenAI "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_inference/openai/openai_batch_embeddings_client.py"
    click Anthropic "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_inference/anthropic/anthropic_batch_chat_completions_client.py"
    click Google "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_inference/google/gemini_oai_chat_completions_client.py"
    click CommonOpenAI "https://github.com/typedef-ai/fenic/tree/main/src/fenic/_inference/common_openai/"
    click Logging "https://github.com/typedef-ai/fenic/blob/main/src/fenic/logging.py"
    click Metrics "https://github.com/typedef-ai/fenic/blob/main/src/fenic/core/metrics.py"
    click SchemaSerde "https://github.com/typedef-ai/fenic/blob/main/src/fenic/_backends/schema_serde.py"

    %% Styles
    classDef pythonLayer fill:#cce5ff,stroke:#004085,color:#004085
    classDef rust fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
```
