Skip to content

Commit d6166cd

Browse files
BroccolitoBroccolito
committed
add documentations
1 parent 803fe2f commit d6166cd

7 files changed

Lines changed: 1401 additions & 0 deletions

File tree

‎documentation/architecture.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# UCSF BioRouter — Architecture
2+
3+
UCSF BioRouter is an AI-powered integrated research environment that unifies commercial, institution-hosted, and local large language models (LLMs), AI agents, Information Commons databases, and customizable workflows into one extensible platform for explorative analysis, prototyping, automation, and federated cross-institution collaboration.
4+
5+
**Developed by:** Wanjun Gu (wanjun.gu@ucsf.edu), Baranzini Lab (https://baranzinilab.ucsf.edu/), UCSF
6+
**Supported by:** UCSF IT and Information Commons
7+
**GitHub:** https://github.com/BaranziniLab/BioRouter
8+
**Releases:** https://github.com/BaranziniLab/BioRouter/releases
9+
10+
---
11+
12+
## High-Level Overview
13+
14+
BioRouter is built as a modular, plugin-based system. It consists of three main layers:
15+
16+
1. **Interface** — The desktop GUI or CLI that accepts user input and displays responses.
17+
2. **Agent** — The core reasoning loop that manages LLM interaction, tool execution, and session state.
18+
3. **Extensions** — Pluggable MCP servers that give the agent access to tools (file operations, database queries, web access, code execution, etc.).
19+
20+
In a typical session, the interface starts an agent instance, which connects to one or more extensions simultaneously and routes requests through the selected LLM provider.
21+
22+
---
23+
24+
## Tech Stack
25+
26+
### Backend — Rust
27+
28+
The backend is a Rust workspace (`crates/`) organized into several crates:
29+
30+
| Crate | Purpose |
31+
|---|---|
32+
| `biorouter` | Core agent library — agent loop, provider integrations, session management, recipes, scheduling |
33+
| `biorouter-server` | REST API server (`biorouterd`) that the desktop UI communicates with |
34+
| `biorouter-cli` | Command-line interface (`biorouter` binary) |
35+
| `biorouter-mcp` | Built-in MCP servers (Developer, Computer Controller, Memory, Tutorial, Auto Visualiser) |
36+
| `biorouter-acp` | Agent Communication Protocol support |
37+
| `biorouter-bench` | Benchmarking tools |
38+
| `biorouter-test` | Integration tests |
39+
40+
Key Rust dependencies:
41+
42+
- **tokio** — Async runtime
43+
- **axum** — HTTP web framework for the API server
44+
- **rmcp** — Model Context Protocol implementation
45+
- **reqwest** — HTTP client for provider API calls
46+
- **serde / serde_json** — Serialization
47+
- **tiktoken-rs** — Token counting for context management
48+
- **minijinja** — Jinja-style template engine for recipes
49+
- **tokio-cron-scheduler** — Cron-based job scheduling
50+
- **sqlx (SQLite)** — Persistent session and schedule storage
51+
- **etcetera** — Cross-platform config path resolution (`~/.config/biorouter/` on macOS/Linux)
52+
53+
### Frontend — Electron + React
54+
55+
The desktop application is an Electron app built with React and TypeScript.
56+
57+
| Component | Details |
58+
|---|---|
59+
| Framework | Electron 39 + React 19 |
60+
| Build tool | Vite + Electron Forge |
61+
| Language | TypeScript (strict mode) |
62+
| Styling | TailwindCSS v4 with custom design tokens |
63+
| UI components | Radix UI primitives |
64+
| Routing | React Router DOM v7 |
65+
| Testing | Vitest (unit), Playwright (E2E) |
66+
67+
The frontend communicates with the `biorouterd` REST server (started in the background by the Electron main process) via a local HTTP API. The OpenAPI spec is generated from the Rust server and used to type-safe frontend API calls.
68+
69+
---
70+
71+
## Agent Interaction Loop
72+
73+
The agent operates in a continuous loop:
74+
75+
1. **Human request** — The user sends a message or task through the interface.
76+
2. **Provider chat** — The agent forwards the request plus a list of available tools to the configured LLM provider.
77+
3. **Tool call** — If the LLM decides to invoke a tool, the agent extracts the tool call (JSON) and executes it via the appropriate extension.
78+
4. **Result feedback** — The tool result is returned to the LLM as context.
79+
5. **Context revision** — Old or irrelevant messages are summarized or pruned to manage token usage efficiently.
80+
6. **Final response** — Once all tool calls are complete, the LLM sends a final response to the user.
81+
82+
If a tool call produces an error (invalid JSON, missing tool, etc.), BioRouter captures and returns the error to the model as a tool response, allowing the LLM to self-correct without breaking the session.
83+
84+
---
85+
86+
## Configuration and Data Paths
87+
88+
| Location | Purpose |
89+
|---|---|
90+
| `~/.config/biorouter/config.yaml` | Primary config — providers, API keys, extensions, settings |
91+
| `~/.config/biorouter/sessions/` | Session history (SQLite) |
92+
| `~/.config/biorouter/recipes/` | Saved recipes |
93+
| `~/.config/biorouter/skills/` | BioRouter-specific global skills |
94+
| `~/Library/Application Support/BioRouter/` | Electron app state (macOS) |
95+
96+
The config file is shared between the Desktop UI and the CLI — changes in either interface are reflected in both.
97+
98+
---
99+
100+
## Multi-Model and Multi-Agent Support
101+
102+
BioRouter supports running multiple agents in parallel:
103+
104+
- **Sub-agents** — A recipe can spawn sub-agents to handle parallel tasks, each with its own LLM provider and extension set.
105+
- **Lead/Worker orchestration** — A lead model delegates sub-tasks to worker models, enabling multi-model pipelines.
106+
- **Subrecipes** — Recipes can call other recipes as sub-tasks, running them sequentially or in parallel.
107+
108+
---
109+
110+
## Security
111+
112+
- Extensions are scanned for known malware before activation.
113+
- BioRouter enforces permission modes that control whether tool calls require user approval.
114+
- `.biorouterignore` files can restrict which files and directories the agent is allowed to access.
115+
- Allowlists can restrict which shell commands the agent may execute.

‎documentation/data-privacy.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# UCSF BioRouter — Data Privacy and Patient Data Guidelines
2+
3+
This document outlines the data privacy considerations for using UCSF BioRouter, with specific guidance on handling patient data, clinical information, and other sensitive research data.
4+
5+
---
6+
7+
## Overview
8+
9+
BioRouter routes your inputs and conversation context to an LLM provider for processing. The data privacy properties of any given session depend entirely on **which provider you are using**. Different providers have fundamentally different data handling policies:
10+
11+
- **Commercial cloud APIs** (Anthropic, OpenAI, Google, etc.) — data is processed on the provider's cloud infrastructure. Review the provider's privacy policy and data processing terms before use.
12+
- **Institution-managed cloud services** (UCSF Azure OpenAI, UCSF Amazon Bedrock) — data is processed within infrastructure governed by UCSF's institutional agreements. These may offer stronger privacy protections than personal API accounts.
13+
- **Local models** (Ollama) — data is processed entirely on your own device. Nothing is transmitted to any external service.
14+
15+
---
16+
17+
## Patient Data and Sensitive Research Data
18+
19+
**IMPORTANT NOTICE:**
20+
21+
If you need to work with patient data, protected health information (PHI), clinical records, genomic data linked to individuals, or any data subject to HIPAA, institutional data governance policies, or other regulatory requirements:
22+
23+
- **Use only institution-managed services or fully local models.**
24+
- Do NOT use personal commercial API accounts (e.g., your personal Anthropic API key, personal OpenAI account) with patient or sensitive data.
25+
- The safest option for data that must remain completely private is a **local model via Ollama** — data never leaves your device.
26+
27+
### Recommended Providers for Sensitive Data
28+
29+
| Provider | Data Stays Within | Recommended For |
30+
|---|---|---|
31+
| **Ollama (local)** | Your device only — no external transmission | Highest sensitivity data, air-gapped requirements |
32+
| **UCSF Azure OpenAI** | UCSF's institutional Azure tenant | Institution-approved use cases — verify with your institution |
33+
| **UCSF Amazon Bedrock** | UCSF's institutional AWS environment | Institution-approved use cases — verify with your institution |
34+
35+
### Providers NOT Recommended for Patient Data
36+
37+
The following providers use personal/commercial API accounts and are generally **not appropriate** for patient data without explicit institutional authorization:
38+
39+
- Anthropic (direct API)
40+
- OpenAI (direct API)
41+
- Google Gemini (direct API)
42+
- OpenRouter
43+
- Venice AI
44+
- X.AI (Grok)
45+
- Any other third-party commercial API
46+
47+
---
48+
49+
## Verification Requirement
50+
51+
**Always verify with your institution before working with sensitive data.**
52+
53+
Even institution-managed services (UCSF Azure OpenAI, UCSF Amazon Bedrock) may have specific terms of use, approved use cases, and restrictions that change over time. Before using BioRouter with any sensitive data:
54+
55+
1. Confirm that your intended use case is covered by the institutional data use agreement for that provider.
56+
2. Check with UCSF IT or your IRB/compliance office if you are unsure.
57+
3. Ensure that the data classification level of your data is compatible with the service tier you are using.
58+
59+
UCSF policies around data handling, HIPAA compliance, and acceptable use of cloud services evolve. The BioRouter development team cannot advise on the current status of institutional agreements. Always check directly with UCSF compliance and IT.
60+
61+
---
62+
63+
## Best Practices for Data Handling
64+
65+
**De-identify before using BioRouter:**
66+
- Remove names, dates of birth, medical record numbers, addresses, and other direct identifiers before inputting clinical data into any BioRouter session, unless you have explicit authorization and a compliant data pathway to do so with identifiers present.
67+
68+
**Minimize data exposure:**
69+
- Provide only the data necessary for the task. Avoid pasting entire datasets into the chat when a representative sample or summary would suffice.
70+
71+
**Use local models when possible:**
72+
- For exploratory work, algorithm development, or testing with real data, Ollama with a capable local model is the safest option.
73+
74+
**Review session logs:**
75+
- BioRouter logs sessions locally. Be aware that session history stored in `~/.config/biorouter/` on your device may contain data you entered. Protect access to your device accordingly.
76+
77+
**Do not share sessions containing sensitive data:**
78+
- BioRouter supports sharing sessions and recipes. Do not share sessions that contain patient data or other sensitive information.
79+
80+
---
81+
82+
## Summary
83+
84+
| Data Type | Recommended Approach |
85+
|---|---|
86+
| De-identified research data | Institution-managed providers or local Ollama |
87+
| Patient data / PHI | Local Ollama only, or institution-managed with explicit compliance approval |
88+
| Public / non-sensitive data | Any provider |
89+
| Proprietary unpublished research data | Local Ollama or institution-managed — verify confidentiality requirements |
90+
91+
**When in doubt: use Ollama (local) or check with your institution.**
92+
93+
---
94+
95+
## Contact
96+
97+
UCSF BioRouter is developed by Wanjun Gu (wanjun.gu@ucsf.edu) at the Baranzini Lab (https://baranzinilab.ucsf.edu/) at UCSF, with support from UCSF IT and Information Commons.
98+
99+
For questions about data governance, HIPAA compliance, and approved data use pathways, contact UCSF IT Security or your departmental compliance officer.

0 commit comments

Comments
 (0)