# future-house/data-analysis-crow architecture

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

- Interactive diagram: https://gitdiagram.com/future-house/data-analysis-crow
- Repository: https://github.com/future-house/data-analysis-crow

## Overview

##### Project Type and Purpose
- This is a Python-based AI agent framework (“Data Analysis Crow”) that orchestrates iterative Jupyter-notebook–driven data analyses.
- It provides:
- A CLI/API to accept datasets + prompts
- A notebook-building engine using Jinja2 templates
- Integration with LLMs (via litellm)
- A Dockerized environment for bioinformatics packages
- Scripts to run BixBench benchmark experiments

##### File Structure
- Top-level:
- src/fhda – core library (config, dataset handling, model logic, storage, templates, utils)
- src/expts – experiment harness (client/server, dsbench, eval, training)
- src/scripts/bixbench_evaluation – evaluation runner (YAML configs, run.sh)
- tutorial – example notebooks and datasets
- CI/config files (.github, pre-commit, Dockerfile)
- Key patterns:
- Modular library (src/fhda)
- Experiment orchestration (src/expts + scripts)
- Notebook templating (Jinja2 in src/fhda/templates)
- Config via YAML (.env, dev.yaml, server.yaml, runner.yaml)

##### Extract Architecture Insights from README
- Core flow:
1. User invokes CLI / Python API with dataset + prompt
2. Agent loads config & dataset definitions (dataset.py)
3. Agent queries LLM APIs (litellm clients)
4. Agent uses templates to build notebook cells (Jinja2)
5. Agent executes notebook (Jupyter server or papermill inside Docker)
6. Results & intermediate notebooks are stored/logged
7. For BixBench: runner.sh drives experiments, collects trajectories

##### Main Components
a. User Interface Layer
– CLI / Python API entry point
– Configuration subsystem (.env, dev.yaml, runner.yaml, server.yaml)
b. Agent Core
– Experiment harness (src/expts: client.py, server.py, dsbench.py, training.py, eval.py)
– fhda library modules (config.py, dataset.py, models.py, storage.py, utils.py)
– Prompt & template renderer (src/fhda/prompts.py + src/fhda/templates)
c. Execution Environment
– Notebook engine (Jupyter server or papermill process)
– Docker container (Dockerfile.pinned) with bioinformatics packages
d. External Services & APIs
– LLM providers (OpenAI, Anthropic, etc. via litellm)
– Optional storage (local filesystem or remote storage via storage.py)
– BixBench benchmark repo (scripts/bixbench_evaluation)
e. Data Stores
– Input datasets (local files, Hugging Face)
– Generated notebooks & outputs (tutorial/tmp_results_dir or user-specified output dir)
– Logs/metrics (expt_logging.py)

##### Relationships and Data Flows
- User → CLI/API → loads Config
- Agent Core → Dataset module → fetches dataset
- Agent Core → Prompt module → sends prompt to LLM API
- LLM API → returns code snippets / analysis steps
- Agent Core → Template renderer → constructs notebook cells
- Agent Core → Notebook Engine → executes notebook
- Notebook Engine → writes results/notebooks → Storage
- Experiment Runner (scripts) → orchestrates repeated agent runs → aggregates metrics

##### Architectural Patterns & Principles
- Layered modular design (separate config, data, model, template, execution)
- Plug-in style for different runtimes (Python/R/Bash) via notebook engine
- Experiment/Reproducibility focus (YAML configs, logging, scripts)
- Containerization for consistency (Dockerfile.pinned)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top external services
    LLM["LLM Providers<br/>(OpenAI, Anthropic)<br/>via litellm"]:::external

    %% Middle layer containers
    subgraph "User & Config Layer"
        direction LR
        CLI["CLI/API Entry Point"]:::config
        CFG1["config.py"]:::config
        CFG2["dev.yaml"]:::config
        CFG3["config.py<br/>(scripts)"]:::config
        CFG4["runner.yaml"]:::config
        CFG5["server.yaml"]:::config
    end

    subgraph "Agent Core"
        direction LR
        subgraph "Core Library"
            direction TB
            LIB_CFG["config.py"]:::compute
            LIB_DS["dataset.py"]:::compute
            LIB_MOD["models.py"]:::compute
            LIB_STG["storage.py"]:::compute
            LIB_UTIL["utils.py"]:::compute
        end
        subgraph "Prompt & Templates"
            direction TB
            PRM["prompts.py"]:::compute
            TPL[".j2 Templates"]:::compute
        end
        subgraph "Experiment Harness"
            direction TB
            EH_CL["client.py"]:::compute
            EH_SR["server.py"]:::compute
            EH_DB["dsbench.py"]:::compute
            EH_EV["eval.py"]:::compute
            EH_TR["training.py"]:::compute
        end
    end

    subgraph "Execution & Storage"
        direction LR
        NB_EXEC["Notebook Executor<br/>(Jupyter/papermill)"]:::compute
        BIO_ENV["Docker Env<br/>(bioinfo pkgs)"]:::compute
        DS_IN["Input Datasets"]:::datastore
        DS_OUT["Generated Notebooks & Outputs"]:::datastore
        LOGS["Logs & Metrics"]:::datastore
    end

    %% Bottom external runner
    BBench["BixBench Runner<br/>(run.sh)"]:::external

    %% Connections
    LLM -->|get prompt response| PRM
    CLI -->|load config| CFG1
    CFG1 --> LIB_CFG
    CFG2 --> LIB_CFG
    CFG3 --> LIB_CFG
    CFG4 --> LIB_CFG
    CFG5 --> LIB_CFG

    LIB_CFG --> LIB_DS
    LIB_DS --> DS_IN
    LIB_MOD --> LLM
    EH_CL --> LIB_MOD
    PRM --> TPL
    TPL --> NB_EXEC
    NB_EXEC -->|execute cells| DS_OUT
    NB_EXEC -->|execute cells| LOGS
    BIO_ENV --> NB_EXEC
    EH_DB --> EH_CL
    EH_EV --> LOGS
    EH_TR --> LOGS
    BBench --> EH_CL
    BBench --> LOGS

    %% Click events
    click CLI "https://github.com/future-house/data-analysis-crow/blob/main/pyproject.toml"
    click CFG1 "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/config.py"
    click CFG2 "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/dev.yaml"
    click CFG3 "https://github.com/future-house/data-analysis-crow/blob/main/src/scripts/config.py"
    click CFG4 "https://github.com/future-house/data-analysis-crow/blob/main/src/scripts/bixbench_evaluation/runner.yaml"
    click CFG5 "https://github.com/future-house/data-analysis-crow/blob/main/src/scripts/bixbench_evaluation/server.yaml"

    click EH_CL "https://github.com/future-house/data-analysis-crow/blob/main/src/expts/client.py"
    click EH_SR "https://github.com/future-house/data-analysis-crow/blob/main/src/expts/server.py"
    click EH_DB "https://github.com/future-house/data-analysis-crow/blob/main/src/expts/dsbench.py"
    click EH_EV "https://github.com/future-house/data-analysis-crow/blob/main/src/expts/eval.py"
    click EH_TR "https://github.com/future-house/data-analysis-crow/blob/main/src/expts/training.py"

    click LIB_CFG "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/config.py"
    click LIB_DS "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/dataset.py"
    click LIB_MOD "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/models.py"
    click LIB_STG "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/storage.py"
    click LIB_UTIL "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/utils.py"

    click PRM "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/prompts.py"
    click TPL "https://github.com/future-house/data-analysis-crow/tree/main/src/fhda/templates/"

    click NB_EXEC "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/notebook_env.py"
    click BIO_ENV "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/Dockerfile.pinned"
    click BIO_ENV "https://github.com/future-house/data-analysis-crow/blob/main/src/fhda/kernel_requirements.txt"

    click BBench "https://github.com/future-house/data-analysis-crow/blob/main/src/scripts/bixbench_evaluation/run.sh"
    click LOGS "https://github.com/future-house/data-analysis-crow/blob/main/src/scripts/expt_logging.py"
    click DS_IN "https://github.com/future-house/data-analysis-crow/tree/main/tutorial/datasets/"
    click DS_OUT "https://github.com/future-house/data-analysis-crow/tree/main/tutorial/tmp_results_dir/"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#02457A,color:#02457A;
    classDef datastore fill:#DFF2D8,stroke:#237A1C,color:#237A1C;
    classDef external fill:#E8E8E8,stroke:#888888,color:#333333,stroke-dasharray: 5 5;
    classDef config fill:#FFE5B4,stroke:#D97706,color:#92400E;
```
