# future-house/robin architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source Python framework and CLI (via Jupyter notebooks) called “Robin,” designed to orchestrate a multi‐agent workflow for scientific discovery.
- It provides reusable modules to generate experimental assay hypotheses, literature reviews, therapeutic candidate proposals, and optional data analysis, then writes structured outputs to disk.

##### File structure
Top-level layout:
- pyproject.toml / uv.lock – dependency and lock files
- robin/ – core Python package
– configuration.py: load API keys, set up RobinConfiguration
– prompts.py: text templates for queries
– assays.py: experimental assay generation
– candidates.py: therapeutic candidate generation
– analyses.py: optional data analysis (Finch agent)
– multitrajectory_runner.py: high-level orchestrator for multi‐step flows
– utils.py: common helpers, I/O routines
- robin_demo.ipynb & robin_full.ipynb – user-facing notebooks to run workflows
- examples/ – static sample outputs for 10 diseases, demonstrating folder structure and file types
- robin_output/ – the runtime output directory created per run (timestamped disease subfolder)
- .github/ & CI configs – build and test automation

##### README insights
- System relies on environment variables or explicit config for LLM keys (OpenAI, other LiteLLM backends) and FutureHouse API.
- Core workflow:
– Instantiate RobinConfiguration (disease, API keys, model)
– Generate and rank experimental assays (assays.py)
– Generate and rank therapeutic candidates (candidates.py)
– Optionally run data analysis via FutureHouse Finch agent (analyses.py)
– Save outputs: text files, CSV rankings, summary files, nested in robin_output/<disease_timestamp>

a. Main components
1. User Interface
– Jupyter Notebook front-end (CLI wrapper)
– Python REPL / script entrypoint
2. Application Core
– robin.configuration → loads keys, parameters
– robin.multitrajectory_runner → orchestrates the sequence
– robin.assays → Experimental Assay Agent
– robin.candidates → Therapeutic Candidate Agent
– robin.analyses → Data Analysis Agent (Finch)
– robin.prompts → Query templates
– robin.utils → File I/O, logging
3. External Services
– LLM Providers (OpenAI, other via LiteLLM)
– FutureHouse platform (Finch data analysis agent)
4. File System
– examples/ (static examples)
– robin_output/ (dynamic, timestamped run directories)
b. Relationships and interactions
– Notebook → calls Application Core
– Configuration → passed into each agent
– Agents → make HTTP/API calls to LLM providers or FutureHouse
– Agents → receive responses → robin.utils formats responses → writes to robin_output
– Multitrajectory_runner → loops over assays/candidates → aggregates rankings → triggers optional analysis
c. Architectural patterns
– Orchestration pattern: multitrajectory_runner as a coordinator
– Agent pattern: separate modules for distinct responsibilities (hypotheses, literature review, ranking)
– Template method: prompts.py provides reusable text templates
– Plug-in/extensibility: configurable LLM backends via LiteLLM, optional analysis stage
d. Key technologies and libraries
– Python 3.12+
– LiteLLM (abstracts multiple LLM providers)
– requests or httpx for API communication
– pandas (for CSV reading/writing, ranking)
– Jupyter notebooks (user interface)
– CI: GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        NB["Notebook/CLI"]:::ui
    end

    subgraph "Application Core"
        Config["Configuration"]:::core
        Runner["Multitrajectory Runner"]:::core
        Prompts["Prompt Templates"]:::core
        Assay["Experimental Assay Agent"]:::core
        Candidate["Therapeutic Candidate Agent"]:::core
        Utils["Utilities"]:::core
        subgraph "Optional Analysis Stage"
            Analysis["Data Analysis Agent"]:::core
        end
        Pyproject["pyproject.toml"]:::core
        Init["robin/__init__.py"]:::core
    end

    subgraph "External Services"
        LLM["LLM Providers"]:::external
        Finch["FutureHouse Finch"]:::external
    end

    subgraph "Storage"
        Examples["Static Examples"]:::storage
        Outputs["Runtime Outputs"]:::storage
    end

    subgraph "CI / Automation"
        CI1["Build CI"]:::ci
        CI2["Test CI"]:::ci
    end

    NB -->|"loads"| Config
    Config -->|"passes into"| Runner
    Runner -->|"uses"| Assay
    Runner -->|"uses"| Candidate
    Runner -->|"triggers"| Analysis
    Prompts -->|"templates for"| Assay
    Prompts -->|"templates for"| Candidate
    Prompts -->|"templates for"| Analysis
    Assay -->|"calls"| LLM
    Candidate -->|"calls"| LLM
    Analysis -->|"calls"| Finch
    Assay -->|"outputs to"| Utils
    Candidate -->|"outputs to"| Utils
    Analysis -->|"outputs to"| Utils
    Utils -->|"writes to"| Outputs
    NB -->|"shows examples"| Examples

    click NB "https://github.com/future-house/robin/blob/main/robin_demo.ipynb"
    click NB "https://github.com/future-house/robin/blob/main/robin_full.ipynb"
    click Config "https://github.com/future-house/robin/blob/main/robin/configuration.py"
    click Runner "https://github.com/future-house/robin/blob/main/robin/multitrajectory_runner.py"
    click Assay "https://github.com/future-house/robin/blob/main/robin/assays.py"
    click Candidate "https://github.com/future-house/robin/blob/main/robin/candidates.py"
    click Analysis "https://github.com/future-house/robin/blob/main/robin/analyses.py"
    click Prompts "https://github.com/future-house/robin/blob/main/robin/prompts.py"
    click Utils "https://github.com/future-house/robin/blob/main/robin/utils.py"
    click Pyproject "https://github.com/future-house/robin/blob/main/pyproject.toml"
    click Init "https://github.com/future-house/robin/blob/main/robin/__init__.py"
    click Examples "https://github.com/future-house/robin/tree/main/examples/"
    click Outputs "https://github.com/future-house/robin/tree/main/robin_output/"
    click CI1 "https://github.com/future-house/robin/blob/main/.github/workflows/build.yml"
    click CI2 "https://github.com/future-house/robin/blob/main/.github/workflows/tests.yml"

    classDef ui fill:#D6E9FE,stroke:#4A90E2,color:#000;
    classDef core fill:#DFF2BF,stroke:#4F8A10,color:#000;
    classDef external fill:#FEEFB3,stroke:#9F6000,color:#000;
    classDef storage fill:#E0E0E0,stroke:#666,color:#000;
    classDef ci fill:#EFE0FF,stroke:#8855AA,color:#000;
```
