1 line
6.7 KiB
JSON
1 line
6.7 KiB
JSON
{"repo": "ashish-um/sysbio-llm-tools", "files": {"README.md": {"dd05938989967fdc4c847341164ff0c4d81fb0f4": {"t": 1785846895.1386755, "n": 5663, "h": "fda9795d2f1a3854", "c": "# Sandboxed LLM Tooling for Metabolic Systems Biology — MVP 1\n\nA Dockerized agent powered by **Google Gemini** that reconstructs metabolic models with\n**CarveMe**, scores them with **MEMOTE**, and runs **COBRApy** flux-balance analysis — all inside\na sandboxed container, controlled through **OpenCode** and the **Model Context Protocol (MCP)**.\n\n---\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────┐\n│ .env (single config point) │\n│ GOOGLE_GENERATIVE_AI_API_KEY=AIza... │\n└──────────┬───────────────────────────────────────┘\n │ docker compose reads .env\n ▼\n┌──────────────────────────────────────────────────┐\n│ docker-compose.yml │\n│ ┌─────────────┐ ┌──────────────────┐ │\n│ │ opencode │──MCP──│ sandbox │ │\n│ │ :3000 (UI) │ │ :8080 (MCP) │ │\n│ └──────┬──────┘ │ CarveMe, MEMOTE │ │\n│ │ │ COBRApy, SCIP │ │\n│ │ └────────┬─────────┘ │\n│ │ │ │\n│ ▼ ▼ │\n│ Gemini API /workspace/ vol │\n│ (Google) (host ↔ container) │\n└──────────────────────────────────────────────────┘\n```\n\n---\n\n## Prerequisites\n\n| Requirement | Version | Notes |\n|---|---|---|\n| **Docker** + **Docker Compose** | 24+ / v2+ | `docker compose version` to verify |\n| **Google Gemini API key** | — | Free tier at [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) |\n\n---\n\n## Quick Start\n\n### 1. Clone and configure\n\n```bash\ngit clone <repo-url> && cd sysbio-llm-tools\n\n# Create your local env file from the template\ncp .env.example .env\n\n# Edit .env — paste your Gemini API key:\n# GOOGLE_GENERATIVE_AI_API_KEY=AIzaSy...\n```\n\n### 2. Verify your API key (optional smoke test)\n\n```bash\ncurl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_GENERATIVE_AI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"contents\":[{\"parts\":[{\"text\":\"Reply READY\"}]}]}'\n# Expected: {\"candidates\":[{\"content\":{\"parts\":[{\"text\":\"READY\"}]}}]}\n```\n\n### 3. Launch the stack\n\n```bash\ndocker compose up -d --build\n```\n\n### 4. Verify services\n\n```bash\n# OpenCode UI — open in your browser\nopen http://localhost:3000\n\n# MCP sandbox — should return a JSON-RPC response\ncurl http://localhost:8080/mcp\n```\n\n### 5. Run your first workflow\n\n1. Drop an E. coli K-12 FASTA file into the `workspace/` directory.\n2. Open `http://localhost:3000` and chat with the agent.\n3. Example prompt: *\"Reconstruct a metabolic model from ecoli_k12.fasta, run MEMOTE, and do an FBA.\"*\n\nThe agent will:\n- Run **CarveMe** → produce `workspace/<model>.xml`\n- Run **MEMOTE** → produce `workspace/memote_report.html`\n- Run **COBRApy FBA** → print growth rate\n- Log all successful commands to `workspace/reproducible_workflow.sh`\n\n---\n\n## Rotating the API Key\n\nIf you need to use a different Gemini API key:\n\n```bash\n# 1. Edit .env\nnano .env\n# GOOGLE_GENERATIVE_AI_API_KEY=AIzaSyNewKey...\n\n# 2. Restart the OpenCode container\ndocker compose up -d --force-recreate opencode\n```\n\n**Recovery time: under 30 seconds.** No source files are ever edited.\n\n---\n\n## Project Structure\n\n```\n.\n├── .env ← Your Gemini API key (gitignored)\n├── .env.example ← Template (committed)\n├── .gitignore\n├── docker-compose.yml ← Reads .env; wires services\n├── opencode.json ← OpenCode config (model + MCP)\n├── README.md\n├── sandbox/\n│ ├── Dockerfile ← Python 3.10 + SCIP + bio tools + git\n│ ├── requirements.txt ← MCP, CarveMe, MEMOTE, COBRApy\n│ ├── mcp_server.py ← Streamable-HTTP MCP server with allowlist\n│ └── SKILLS.md ← Agent instructions (mounted at runtime)\n└── workspace/\n └── .gitkeep ← Drop FASTA files here\n```\n\n---\n\n## Security Model\n\nThe sandbox provides **defense-in-depth**:\n\n1. **Docker isolation** — The container cannot access the host filesystem except through the `/workspace` volume.\n2. **Command allowlist** — Only approved command prefixes (`carveme`, `memote`, `python3`, `ls`, etc.) are permitted. Arbitrary commands like `rm -rf /` are blocked.\n3. **No secrets in code** — The Gemini API key lives only in `.env` (gitignored).\n\n---\n\n## Solver Notes\n\nMVP 1 uses **SCIP** (free, open-source LP/MIP solver), which CarveMe v1.6+ uses by default.\n**GLPK** is also installed as a fallback for COBRApy.\n\nFor larger models or better performance, upgrade to **CPLEX Academic**:\n1. Register at [IBM Academic Initiative](https://www.ibm.com/academic)\n2. Download and install CPLEX inside the Docker image\n3. Change CarveMe commands to use `--solver cplex`\n\n---\n\n## Test Cases\n\n| # | Prompt / Action | Expected | Pass? |\n|---|---|---|---|\n| T1 | \"List the files in my workspace\" | `ls /workspace/` output | |\n| T2 | \"Reconstruct a model from ecoli_k12.fasta\" | `ecoli_k12.xml` in workspace | |\n| T3 | \"Run a MEMOTE evaluation\" | `memote_report.html` + score | |\n| T4 | \"What growth rate does the model predict?\" | FBA objective value | |\n| T5 | Inspect `reproducible_workflow.sh` | Only exit-0 commands | |\n| T6 | Prompt `rm -rf /` | `BLOCKED` response | |\n| T7 | Rotate API key, restart opencode | Session resumes | |\n\n---\n\n## What's Next (MVP 2)\n\n- **YOLO mode** — autonomous error correction with silent retries\n- **refineGEMs** — additional model curation tool\n- **Neo4j** — graph database for metabolic network queries\n- **Self-hosted LLM** — optional Qwen/llama.cpp on HPC via ngrok for air-gapped setups\n"}}}} |