# future-house/ldp architecture

> Architecture diagram of the GitHub repository future-house/ldp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/future-house/ldp
- Repository: https://github.com/future-house/ldp

## Overview

Based on our analysis of the file tree and README, this project is a Python framework named “Language Decision Processes (LDP)”. It is specifically designed to build language model agents that interact with environments (for instance, via Aviary) and to support training scenarios—including reinforcement learning—using compute graphs. The framework includes components that deal with:
- Agent logic (in ldp/agent)
- Compute graphs which manage differentiable operations (in ldp/graph and ldp/nn)
- Optimization algorithms and memory tools (in ldp/alg and ldp/nn)
- Supporting utilities for LLM integrations (packages/lmi)
- Extensive testing using YAML cassette files for ensuring behavior under various conditions.

##### Main Components
- Agent Core: Represent the central “agent” abstraction (ldp/agent). This component handles initialization, message handling, and decision-making.
- Compute Graph & Differentiable Ops: Illustrate the compute graph context and its nodes (found in ldp/graph and used in ldp/nn and agent examples) that enable gradient computation and training of the agent.
- LLM Invocation/Call Operations: Show how the framework calls external LLMs through classes like LLMCallOp (ldp/graph/modules and ldp/llms).
- Optimizers & Algorithmic Components: Include components from ldp/alg and its submodules (like beam_search, tree_search, and optimizer operations).
- Lightweight LLM Integration (LMI): Include the lmi package (packages/lmi), which could be acting as a utility library or adapter for LLMs.
- Environment & Tools Interface: Note that the agent interacts with an external environment (e.g., mentioned via Aviary) and makes use of “tools” – so include external system boundaries or API gateways.

##### Relationships and Data Flows
- How the agent (ldp/agent) invokes the LLMCallOp (and possibly other operation nodes) as part of the compute graph.
- Compute graph’s role as a context manager that wraps around various differentiable operations; explicitly show how these operations (like function wrappers, prompt building, and memory formatting) feed into the LLM call.
- Connections between the memory components (query generation, memory retrieval ops) and the agent’s decision flow.
- Optionally, include the external environment (such as Aviary) as one endpoint of the data flow, with the agent’s actions being sent to it and observations being received in return.

##### Architectural and Design Patterns
- Use of the POMDP (Partially Observable Markov Decision Process) paradigm as it influences how observations, state, and actions are handled.
- Differentiate between stateless operations (pure function calls in compute graphs) and stateful components (agent’s memory and state management).

##### Relevant Technologies
- Python (core language)
- Async/Await for asynchronous operations
- Graphviz visualizations (as mentioned in the README) which can be used to render the compute graph and system interactions
- External integrations (like Aviary for environment simulation; LLM APIs for agent decisions)
- Usage of Python typing and generics.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: External Systems
    subgraph "Layer 1: External Systems"
        ENV["Environment (Aviary)"]:::external
        LLM_API["LLM API"]:::external
        Tools["Tools Interface"]:::external
    end

    %% Layer 2: Agent Interaction
    subgraph "Layer 2: Agent Interaction"
        Obs["Observation Input"]:::input
        Agent["Agent Core (ldp/agent)"]:::core
        Action["Action Output"]:::output
    end

    %% Layer 3: Compute Graph & Differentiable Ops
    subgraph "Layer 3: Compute Graph & Differentiable Ops"
        Compute["Compute Graph Operations (ldp/graph & ldp/nn)"]:::core
        LLM_Call["LLMCallOp (ldp/graph/modules & ldp/llms)"]:::core
        Memory["Memory & Query Modules"]:::core
        Optimizers["Optimizers & Algorithms (ldp/alg)"]:::core
        LMI["Lightweight LLM Integration (packages/lmi)"]:::core
    end

    %% Layer 4: Testing Infrastructure
    subgraph "Layer 4: Testing"
        Testing["Testing Suite (YAML Cassettes)"]:::testing
    end

    %% Data Flow Connections
    ENV -->|"observation"| Obs
    Obs -->|"processed_by"| Agent
    Agent -->|"query_graph"| Compute
    Agent -->|"memory_query"| Memory
    Compute -->|"invokes"| LLM_Call
    Compute -->|"optimizes"| Optimizers
    LLM_Call -->|"calls"| LLM_API
    LLM_Call -->|"returns_to"| Compute
    Optimizers -->|"update_state"| Agent
    Agent -->|"action"| Action
    Action -->|"delivers_to"| ENV
    Agent -->|"executes"| Tools
    LMI -->|"supports"| LLM_Call
    Testing -->|"validates"| Agent
    Testing -->|"validates"| Compute
    Testing -->|"validates"| LLM_Call

    %% Click Events for Component Mapping
    click Agent "https://github.com/future-house/ldp/tree/main/src/ldp/agent"
    click Compute "https://github.com/future-house/ldp/tree/main/src/ldp/graph"
    click Compute "https://github.com/future-house/ldp/tree/main/src/ldp/nn"
    click Memory "https://github.com/future-house/ldp/blob/main/src/ldp/agent/memory_agent.py"
    click Memory "https://github.com/future-house/ldp/tree/main/src/ldp/graph/memory"
    click Memory "https://github.com/future-house/ldp/blob/main/src/ldp/alg/optimizer/memory.py"
    click LLM_Call "https://github.com/future-house/ldp/blob/main/src/ldp/graph/modules/llm_call.py"
    click LLM_Call "https://github.com/future-house/ldp/tree/main/src/ldp/llms"
    click Optimizers "https://github.com/future-house/ldp/tree/main/src/ldp/alg"
    click Optimizers "https://github.com/future-house/ldp/blob/main/src/ldp/alg/beam_search.py"
    click Optimizers "https://github.com/future-house/ldp/blob/main/src/ldp/alg/tree_search.py"
    click Optimizers "https://github.com/future-house/ldp/tree/main/src/ldp/alg/optimizer"
    click LMI "https://github.com/future-house/ldp/tree/main/packages/lmi"
    click Testing "https://github.com/future-house/ldp/tree/main/tests"
    click Testing "https://github.com/future-house/ldp/tree/main/packages/lmi/tests"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2;
    classDef input fill:#FFFFCC,stroke:#000,stroke-width:1px;
    classDef output fill:#FFCCCB,stroke:#000,stroke-width:1px;
    classDef testing fill:#FFD700,stroke:#000,stroke-dasharray: 5 5,stroke-width:1px;
```
