# stephen-smj/lambda architecture

> Architecture diagram of the GitHub repository stephen-smj/lambda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stephen-smj/lambda
- Repository: https://github.com/stephen-smj/lambda

## Overview

##### Project Type and Purpose
- LAMBDA is a code-free, multi-agent data analysis system that lets users perform complex data analysis tasks using natural language. It relies on large language models and features two core agent roles – the “programmer” (to generate code) and the “inspector” (to debug/validate code). The system is designed to be extendable, and it integrates a user interface, optional knowledge integration modules, and support for exporting results (e.g., to Jupyter Notebooks).

##### File Structure
- Key files at the project root include:
- app.py – likely the main entry point to launch the application.
- config.yaml – configuration for API keys, external LLM endpoints, caching, and run-time parameters.
- LICENSE, README.md – standard metadata.
- There are specialized modules:
- conversation.py, kernel.py – likely handling natural language interactions and possibly the backend orchestration.
- programmer.py and inspector.py – implementing the two main agent roles.
- cache/ directory – contains caching mechanisms (cache.py) for conversation or results.
- knowledge_integration/ – holds modules (knw.py, ncm.py, nn_network.py, pami.py) that manage external knowledge retrieval / integration.
- prompt_engineering/ – contains prompts.py, signaling that prompts are carefully crafted to interact with LLMs.
- front_end/ – holds CSS and JavaScript files, representing the user interface elements.
- Additional files like display.py, lambda_utils.py, and knw_in.py that likely support system utility functions.

##### Key System Components to Capture
a. User Interface Layer:
- front_end folder (CSS/JS) represents the GUI that allows the user to control the system.
- It communicates with the backend via app.py.

b. Core Application and Controller:
- app.py serves as the main entry point.
- It orchestrates the interactions between user input and the various agents.
- config.yaml acts as a configuration centre for API keys, model endpoints, cache paths, etc.

c. Agent Modules:
- Programmer Agent (programmer.py) – receives tasks from the user’s natural language instructions and generates code for data analysis.
- Inspector Agent (inspector.py) – examines the output or generated code, likely for debugging and validation.
- Conversation Module (conversation.py and kernel.py) – likely responsible for handling dialogue management and LLM interactions.

d. Knowledge Integration:
- Folder knowledge_integration holds components (such as knw.py, ncm.py, and others) that support knowledge retrieval/integration if enabled. A separate knw_in.py might serve as an interface or additional layer for this functionality.

e. Support Utilities:
- Cache Module (cache/cache.py) – mechanisms to cache interactions or analysis results.
- Prompt Engineering (prompt_engineering/prompts.py) – contains predefined prompts ensuring a robust interaction with language models.
- lambda_utils.py and others deliver additional utility functions helping with data flow, error handling, or configuration.

##### Relationships and Interactions
- The user interacts with the GUI (front_end) and submits data/queries that are handled by app.py.
- app.py reads configuration (config.yaml) and directs tasks to the appropriate agents:
- The conversation and kernel modules manage the prompt flow.
- The programmer agent receives tasks (possibly via conversation.py) and generates code.
- The inspector agent reviews the code/output, possibly feeding back corrections or further instructions.
- If knowledge integration is enabled, the related modules process external data or inputs which are fed into the agents.
- The cache module supports performance improvements and faster retrievals.
- Additionally, prompt engineering ensures that language model queries are well-structured and the system is robust in handling adjustments.

##### Architectural Patterns to Highlight
- Multi-agent Design: Emphasize the separation of responsibilities for different agents (programming, inspection, conversation, and knowledge integration).
- Modular Design: Each directory/module encapsulates a specific function of the system, adhering to separation of concerns.
- Configuration-driven Behavior: The use of config.yaml demonstrates a pattern where runtime behavior can be modified without changing code.
- UI/UX and API Separation: The front_end directory clearly distinguishes the UI from the underlying agent logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["CSS"] 
        UI2["JavaScript"]
    end

    %% Application/Controller Layer
    subgraph "Application/Controller Layer"
        Config["Configuration (config.yaml)"]
        Controller["Main Controller (app.py)"]
    end

    %% Agent Modules Layer
    subgraph "Agent Modules"
        Programmer["Programmer Agent (programmer.py)"]
        Inspector["Inspector Agent (inspector.py)"]
        subgraph "Conversation Management"
            Conversation["Conversation (conversation.py)"]
            Kernel["Kernel (kernel.py)"]
            Conversation ---|"interacts"| Kernel
        end
        subgraph "Knowledge Integration"
            KI["Knowledge Integration Module (knowledge_integration)"]
            KNW["KNW Interface (knw_in.py)"]
            KI ---|"interfaces"| KNW
        end
    end

    %% Utility Modules Layer
    subgraph "Utility Modules"
        CacheUtility["Cache Utility (cache/cache.py)"]
        PromptUtility["Prompt Engineering (prompt_engineering/prompts.py)"]
        Display["Display Utility (display.py)"]
        LambdaUtils["Lambda Utils (lambda_utils.py)"]
    end

    %% Connections between Layers
    UI1 -->|"submits"| Controller
    UI2 -->|"submits"| Controller
    Config -->|"reads"| Controller
    Controller -->|"routesTo"| Programmer
    Controller -->|"routesTo"| Inspector
    Controller -->|"routesTo"| Conversation
    Controller -->|"routesTo"| KI
    Inspector -->|"feedback"| Programmer
    KI -->|"supplies"| Programmer
    KI -->|"supplies"| Conversation
    Controller -->|"uses"| CacheUtility
    Controller -->|"uses"| PromptUtility
    Controller -->|"uses"| Display
    Controller -->|"uses"| LambdaUtils

    %% Click Events
    click UI1 "https://github.com/stephen-smj/lambda/blob/main/front_end/css.css"
    click UI2 "https://github.com/stephen-smj/lambda/blob/main/front_end/javascript.js"
    click Controller "https://github.com/stephen-smj/lambda/blob/main/app.py"
    click Config "https://github.com/stephen-smj/lambda/blob/main/config.yaml"
    click Programmer "https://github.com/stephen-smj/lambda/blob/main/programmer.py"
    click Inspector "https://github.com/stephen-smj/lambda/blob/main/inspector.py"
    click Conversation "https://github.com/stephen-smj/lambda/blob/main/conversation.py"
    click Kernel "https://github.com/stephen-smj/lambda/blob/main/kernel.py"
    click KI "https://github.com/stephen-smj/lambda/tree/main/knowledge_integration"
    click KNW "https://github.com/stephen-smj/lambda/blob/main/knw_in.py"
    click CacheUtility "https://github.com/stephen-smj/lambda/blob/main/cache/cache.py"
    click PromptUtility "https://github.com/stephen-smj/lambda/blob/main/prompt_engineering/prompts.py"
    click Display "https://github.com/stephen-smj/lambda/blob/main/display.py"
    click LambdaUtils "https://github.com/stephen-smj/lambda/blob/main/lambda_utils.py"

    %% Styles
    classDef ui fill:#c7f7c7,stroke:#333,stroke-width:2px;
    classDef controller fill:#c7eaff,stroke:#333,stroke-width:2px;
    classDef agent fill:#ffe9c7,stroke:#333,stroke-width:2px;
    classDef utility fill:#f3c7ff,stroke:#333,stroke-width:2px;

    class UI1,UI2 ui;
    class Controller,Config controller;
    class Programmer,Inspector,Conversation,Kernel,KI,KNW agent;
    class CacheUtility,PromptUtility,Display,LambdaUtils utility;
```
