├── frontend
    ├── src
    │   ├── vite-env.d.ts
    │   ├── lib
    │   │   ├── utils.ts
    │   │   ├── api.ts
    │   │   └── useExperiment.ts
    │   ├── main.tsx
    │   ├── App.tsx
    │   ├── App.css
    │   ├── components
    │   │   ├── StatusBadge.tsx
    │   │   ├── Console.tsx
    │   │   ├── StreamingMarkdown.tsx
    │   │   ├── Notebook
    │   │   │   ├── NotebookCell.tsx
    │   │   │   ├── AgentNotebook.tsx
    │   │   │   └── ResearchPaper.tsx
    │   │   ├── FindingsRail.tsx
    │   │   ├── CredentialPrompt.tsx
    │   │   └── LabNotebook.tsx
    │   ├── index.css
    │   └── assets
    │   │   └── react.svg
    ├── vite.config.d.ts
    ├── postcss.config.js
    ├── vite.config.ts
    ├── vite.config.js
    ├── .gitignore
    ├── tsconfig.tsbuildinfo
    ├── eslint.config.js
    ├── index.html
    ├── tsconfig.app.json
    ├── tsconfig.node.json
    ├── tsconfig.json
    ├── package.json
    ├── public
    │   └── vite.svg
    ├── tailwind.config.js
    └── README.md
├── requirements.txt
├── .env.example
├── railway.json
├── api_guide.md
├── Dockerfile
├── experiment.py
├── LICENSE
├── logger.py
├── README.md
├── modal_guide.md
├── run_app.py
├── main.py
├── gemini_3_pro_guide.md
├── insights.py
└── api_server.py


/frontend/src/vite-env.d.ts:
--------------------------------------------------------------------------------
1 | /// <reference types="vite/client" />
2 | 


--------------------------------------------------------------------------------
/frontend/vite.config.d.ts:
--------------------------------------------------------------------------------
1 | declare const _default: import("vite").UserConfig;
2 | export default _default;
3 | 


--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
1 | google-genai
2 | anthropic
3 | modal
4 | python-dotenv
5 | rich
6 | fastapi
7 | uvicorn[standard]
8 | python-dotenv
9 | 


--------------------------------------------------------------------------------
/frontend/postcss.config.js:
--------------------------------------------------------------------------------
1 | export default {
2 |     plugins: {
3 |         "@tailwindcss/postcss": {},
4 |         autoprefixer: {},
5 |     },
6 | }
7 | 


--------------------------------------------------------------------------------
/.env.example:
--------------------------------------------------------------------------------
1 | GOOGLE_API_KEY=your_google_api_key_here
2 | ANTHROPIC_API_KEY=your_anthropic_api_key_here
3 | MODAL_TOKEN_ID=your_modal_token_id_here
4 | MODAL_TOKEN_SECRET=your_modal_token_secret_here
5 | 


--------------------------------------------------------------------------------
/frontend/src/lib/utils.ts:
--------------------------------------------------------------------------------
1 | import { type ClassValue, clsx } from "clsx"
2 | import { twMerge } from "tailwind-merge"
3 | 
4 | export function cn(...inputs: ClassValue[]) {
5 |     return twMerge(clsx(inputs))
6 | }
7 | 


--------------------------------------------------------------------------------
/frontend/src/main.tsx:
--------------------------------------------------------------------------------
 1 | import { StrictMode } from 'react'
 2 | import { createRoot } from 'react-dom/client'
 3 | import './index.css'
 4 | import App from './App.tsx'
 5 | 
 6 | createRoot(document.getElementById('root')!).render(
 7 |   <StrictMode>
 8 |     <App />
 9 |   </StrictMode>,
10 | )
11 | 


--------------------------------------------------------------------------------
/railway.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "$schema": "https://railway.app/railway.schema.json",
 3 |   "build": {
 4 |     "builder": "DOCKERFILE",
 5 |     "dockerfilePath": "Dockerfile"
 6 |   },
 7 |   "deploy": {
 8 |     "healthcheckPath": "/api/health",
 9 |     "restartPolicyType": "ON_FAILURE"
10 |   }
11 | }
12 | 


--------------------------------------------------------------------------------
/frontend/src/App.tsx:
--------------------------------------------------------------------------------
 1 | import { LabNotebook } from "@/components/LabNotebook";
 2 | 
 3 | function App() {
 4 |   return (
 5 |     <div className="flex h-screen w-full bg-black text-foreground font-sans antialiased selection:bg-white/20">
 6 |       <LabNotebook />
 7 |     </div>
 8 |   );
 9 | }
10 | 
11 | export default App;
12 | 


--------------------------------------------------------------------------------
/frontend/vite.config.ts:
--------------------------------------------------------------------------------
 1 | import { defineConfig } from 'vite'
 2 | import react from '@vitejs/plugin-react'
 3 | import path from 'path'
 4 | 
 5 | // https://vitejs.dev/config/
 6 | export default defineConfig({
 7 |   plugins: [react()],
 8 |   resolve: {
 9 |     alias: {
10 |       "@": path.resolve(__dirname, "./src"),
11 |     },
12 |   },
13 | })
14 | 


--------------------------------------------------------------------------------
/frontend/vite.config.js:
--------------------------------------------------------------------------------
 1 | import { defineConfig } from 'vite';
 2 | import react from '@vitejs/plugin-react';
 3 | import path from 'path';
 4 | // https://vitejs.dev/config/
 5 | export default defineConfig({
 6 |     plugins: [react()],
 7 |     resolve: {
 8 |         alias: {
 9 |             "@": path.resolve(__dirname, "./src"),
10 |         },
11 |     },
12 | });
13 | 


--------------------------------------------------------------------------------
/frontend/.gitignore:
--------------------------------------------------------------------------------
 1 | # Logs
 2 | logs
 3 | *.log
 4 | npm-debug.log*
 5 | yarn-debug.log*
 6 | yarn-error.log*
 7 | pnpm-debug.log*
 8 | lerna-debug.log*
 9 | 
10 | node_modules
11 | dist
12 | dist-ssr
13 | *.local
14 | 
15 | # Editor directories and files
16 | .vscode/*
17 | !.vscode/extensions.json
18 | .idea
19 | .DS_Store
20 | *.suo
21 | *.ntvs*
22 | *.njsproj
23 | *.sln
24 | *.sw?
25 | 


--------------------------------------------------------------------------------
/api_guide.md:
--------------------------------------------------------------------------------
 1 | # AI Researcher HTTP API
 2 | 
 3 | This document describes the lightweight HTTP API that wraps the existing CLI entrypoint (`main.py`).
 4 | 
 5 | The API **does not** change any of the research logic – it simply spawns the current CLI in a subprocess and streams back everything it prints, so you can build a rich front-end on top.
 6 | 
 7 | ---
 8 | 
 9 | ## Getting started
10 | 
11 | 1. Install dependencies:
12 | 
13 | ```bash
14 | pip install -r requirements.txt


--------------------------------------------------------------------------------
/frontend/tsconfig.tsbuildinfo:
--------------------------------------------------------------------------------
1 | {"root":["./src/app.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/components/console.tsx","./src/components/credentialprompt.tsx","./src/components/findingsrail.tsx","./src/components/labnotebook.tsx","./src/components/statusbadge.tsx","./src/components/streamingmarkdown.tsx","./src/components/notebook/agentnotebook.tsx","./src/components/notebook/notebookcell.tsx","./src/components/notebook/researchpaper.tsx","./src/lib/api.ts","./src/lib/useexperiment.ts","./src/lib/utils.ts"],"version":"5.9.3"}


--------------------------------------------------------------------------------
/frontend/eslint.config.js:
--------------------------------------------------------------------------------
 1 | import js from '@eslint/js'
 2 | import globals from 'globals'
 3 | import reactHooks from 'eslint-plugin-react-hooks'
 4 | import reactRefresh from 'eslint-plugin-react-refresh'
 5 | import tseslint from 'typescript-eslint'
 6 | import { defineConfig, globalIgnores } from 'eslint/config'
 7 | 
 8 | export default defineConfig([
 9 |   globalIgnores(['dist']),
10 |   {
11 |     files: ['**/*.{ts,tsx}'],
12 |     extends: [
13 |       js.configs.recommended,
14 |       tseslint.configs.recommended,
15 |       reactHooks.configs.flat.recommended,
16 |       reactRefresh.configs.vite,
17 |     ],
18 |     languageOptions: {
19 |       ecmaVersion: 2020,
20 |       globals: globals.browser,
21 |     },
22 |   },
23 | ])
24 | 


--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
 1 | # Build stage for frontend
 2 | FROM node:20-slim AS frontend-builder
 3 | WORKDIR /app/frontend
 4 | COPY frontend/package*.json ./
 5 | RUN npm ci
 6 | COPY frontend/ ./
 7 | RUN npm run build
 8 | 
 9 | # Production stage
10 | FROM python:3.11-slim
11 | WORKDIR /app
12 | 
13 | # Install dependencies
14 | COPY requirements.txt ./
15 | RUN pip install --no-cache-dir -r requirements.txt
16 | 
17 | # Copy all Python files from root (not recursively into venv)
18 | COPY api_server.py main.py agent.py orchestrator.py logger.py insights.py ./
19 | 
20 | # Copy built frontend
21 | COPY --from=frontend-builder /app/frontend/dist ./frontend/dist
22 | 
23 | # Expose port (Railway sets PORT env var)
24 | EXPOSE 8000
25 | 
26 | # Start the server
27 | CMD ["python", "api_server.py"]
28 | 


--------------------------------------------------------------------------------
/frontend/index.html:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html lang="en">
 3 | 
 4 | <head>
 5 |   <meta charset="UTF-8" />
 6 |   <link rel="icon" type="image/svg+xml" href="/vite.svg" />
 7 |   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 8 |   <title>AI Researcher</title>
 9 |   <link rel="preconnect" href="https://fonts.googleapis.com">
10 |   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
11 |   <link
12 |     href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&family=Newsreader:ital,wght@0,400;0,500;0,600;1,400;1,500;1,600&display=swap"
13 |     rel="stylesheet">
14 | </head>
15 | 
16 | <body>
17 |   <div id="root"></div>
18 |   <script type="module" src="/src/main.tsx"></script>
19 | </body>
20 | 
21 | </html>


--------------------------------------------------------------------------------
/frontend/src/App.css:
--------------------------------------------------------------------------------
 1 | #root {
 2 |   max-width: 1280px;
 3 |   margin: 0 auto;
 4 |   padding: 2rem;
 5 |   text-align: center;
 6 | }
 7 | 
 8 | .logo {
 9 |   height: 6em;
10 |   padding: 1.5em;
11 |   will-change: filter;
12 |   transition: filter 300ms;
13 | }
14 | .logo:hover {
15 |   filter: drop-shadow(0 0 2em #646cffaa);
16 | }
17 | .logo.react:hover {
18 |   filter: drop-shadow(0 0 2em #61dafbaa);
19 | }
20 | 
21 | @keyframes logo-spin {
22 |   from {
23 |     transform: rotate(0deg);
24 |   }
25 |   to {
26 |     transform: rotate(360deg);
27 |   }
28 | }
29 | 
30 | @media (prefers-reduced-motion: no-preference) {
31 |   a:nth-of-type(2) .logo {
32 |     animation: logo-spin infinite 20s linear;
33 |   }
34 | }
35 | 
36 | .card {
37 |   padding: 2em;
38 | }
39 | 
40 | .read-the-docs {
41 |   color: #888;
42 | }
43 | 


--------------------------------------------------------------------------------
/frontend/tsconfig.app.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
 4 |     "target": "ES2022",
 5 |     "useDefineForClassFields": true,
 6 |     "lib": ["ES2022", "DOM", "DOM.Iterable"],
 7 |     "module": "ESNext",
 8 |     "types": ["vite/client"],
 9 |     "skipLibCheck": true,
10 | 
11 |     /* Bundler mode */
12 |     "moduleResolution": "bundler",
13 |     "allowImportingTsExtensions": true,
14 |     "verbatimModuleSyntax": true,
15 |     "moduleDetection": "force",
16 |     "noEmit": true,
17 |     "jsx": "react-jsx",
18 | 
19 |     /* Linting */
20 |     "strict": true,
21 |     "noUnusedLocals": true,
22 |     "noUnusedParameters": true,
23 |     "erasableSyntaxOnly": true,
24 |     "noFallthroughCasesInSwitch": true,
25 |     "noUncheckedSideEffectImports": true
26 |   },
27 |   "include": ["src"]
28 | }
29 | 


--------------------------------------------------------------------------------
/frontend/tsconfig.node.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
 4 |     "target": "ES2023",
 5 |     "lib": [
 6 |       "ES2023"
 7 |     ],
 8 |     "module": "ESNext",
 9 |     "types": [
10 |       "node"
11 |     ],
12 |     "skipLibCheck": true,
13 |     /* Bundler mode */
14 |     "moduleResolution": "bundler",
15 |     "verbatimModuleSyntax": true,
16 |     "moduleDetection": "force",
17 |     "composite": true,
18 |     "noEmit": false,
19 |     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
20 |     /* Linting */
21 |     "strict": true,
22 |     "noUnusedLocals": true,
23 |     "noUnusedParameters": true,
24 |     "erasableSyntaxOnly": true,
25 |     "noFallthroughCasesInSwitch": true,
26 |     "noUncheckedSideEffectImports": true
27 |   },
28 |   "include": [
29 |     "vite.config.ts"
30 |   ]
31 | }


--------------------------------------------------------------------------------
/frontend/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "target": "ES2020",
 4 |     "useDefineForClassFields": true,
 5 |     "lib": [
 6 |       "ES2020",
 7 |       "DOM",
 8 |       "DOM.Iterable"
 9 |     ],
10 |     "module": "ESNext",
11 |     "skipLibCheck": true,
12 |     /* Bundler mode */
13 |     "moduleResolution": "bundler",
14 |     "allowImportingTsExtensions": true,
15 |     "resolveJsonModule": true,
16 |     "isolatedModules": true,
17 |     "noEmit": true,
18 |     "jsx": "react-jsx",
19 |     /* Linting */
20 |     "strict": true,
21 |     "noUnusedLocals": true,
22 |     "noUnusedParameters": true,
23 |     "noFallthroughCasesInSwitch": true,
24 |     "baseUrl": ".",
25 |     "paths": {
26 |       "@/*": [
27 |         "./src/*"
28 |       ]
29 |     }
30 |   },
31 |   "include": [
32 |     "src"
33 |   ],
34 |   "references": [
35 |     {
36 |       "path": "./tsconfig.node.json",
37 |       "composite": true,
38 |       "allow": true
39 |     }
40 |   ]
41 | }


--------------------------------------------------------------------------------
/experiment.py:
--------------------------------------------------------------------------------
 1 | import modal
 2 | 
 3 | app = modal.App("fib-gpu-test-1")
 4 | 
 5 | image = modal.Image.debian_slim().pip_install("torch")
 6 | 
 7 | @app.function(image=image, gpu="any")
 8 | def calculate_fib_iterative():
 9 |     import torch
10 |     print(f"Using device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU'}")
11 |     
12 |     device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
13 |     
14 |     n = 10
15 |     # Initializing tensors on GPU
16 |     t0 = torch.tensor(0, device=device)
17 |     t1 = torch.tensor(1, device=device)
18 |     
19 |     if n == 0:
20 |         res = t0
21 |     elif n == 1:
22 |         res = t1
23 |     else:
24 |         for i in range(2, n + 1):
25 |             temp = t0 + t1
26 |             t0 = t1
27 |             t1 = temp
28 |         res = t1
29 | 
30 |     print(f"Fibonacci({n}) calculated on {device}: {res.item()}")
31 |     return res.item()
32 | 
33 | @app.local_entrypoint()
34 | def main():
35 |     print("Starting Test 1: Iterative Approach")
36 |     result = calculate_fib_iterative.remote()
37 |     print(f"Result 1: {result}")
38 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2025 mshumer
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/frontend/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "frontend",
 3 |   "private": true,
 4 |   "version": "0.0.0",
 5 |   "type": "module",
 6 |   "scripts": {
 7 |     "dev": "vite",
 8 |     "build": "tsc -b && vite build",
 9 |     "lint": "eslint .",
10 |     "preview": "vite preview"
11 |   },
12 |   "dependencies": {
13 |     "clsx": "^2.1.1",
14 |     "date-fns": "^4.1.0",
15 |     "framer-motion": "^12.23.24",
16 |     "lucide-react": "^0.554.0",
17 |     "react": "^19.2.0",
18 |     "react-dom": "^19.2.0",
19 |     "react-markdown": "^10.1.0",
20 |     "remark-gfm": "^4.0.1",
21 |     "tailwind-merge": "^3.4.0"
22 |   },
23 |   "devDependencies": {
24 |     "@eslint/js": "^9.39.1",
25 |     "@tailwindcss/postcss": "^4.1.17",
26 |     "@tailwindcss/typography": "^0.5.19",
27 |     "@types/node": "^24.10.1",
28 |     "@types/react": "^19.2.5",
29 |     "@types/react-dom": "^19.2.3",
30 |     "@vitejs/plugin-react": "^5.1.1",
31 |     "autoprefixer": "^10.4.22",
32 |     "eslint": "^9.39.1",
33 |     "eslint-plugin-react-hooks": "^7.0.1",
34 |     "eslint-plugin-react-refresh": "^0.4.24",
35 |     "globals": "^16.5.0",
36 |     "postcss": "^8.5.6",
37 |     "tailwindcss": "^4.1.17",
38 |     "typescript": "~5.9.3",
39 |     "typescript-eslint": "^8.46.4",
40 |     "vite": "^7.2.4"
41 |   }
42 | }
43 | 


--------------------------------------------------------------------------------
/frontend/src/components/StatusBadge.tsx:
--------------------------------------------------------------------------------
 1 | import { cn } from "@/lib/utils";
 2 | 
 3 | interface StatusBadgeProps {
 4 |   status: "idle" | "running" | "completed" | "failed" | "planning";
 5 |   className?: string;
 6 | }
 7 | 
 8 | export function StatusBadge({ status, className }: StatusBadgeProps) {
 9 |   const config: Record<StatusBadgeProps["status"], { text: string; dotColor: string; animate?: boolean }> = {
10 |     idle: {
11 |       text: "Idle",
12 |       dotColor: "bg-[#333]",
13 |     },
14 |     running: {
15 |       text: "Running",
16 |       dotColor: "bg-blue-500",
17 |       animate: true,
18 |     },
19 |     planning: {
20 |       text: "Planning",
21 |       dotColor: "bg-purple-500",
22 |       animate: true,
23 |     },
24 |     completed: {
25 |       text: "Done",
26 |       dotColor: "bg-green-500",
27 |     },
28 |     failed: {
29 |       text: "Failed",
30 |       dotColor: "bg-red-500",
31 |     },
32 |   };
33 | 
34 |   const { text, dotColor, animate } = config[status];
35 | 
36 |   return (
37 |     <div className={cn("flex items-center gap-2", className)}>
38 |       <div 
39 |         className={cn(
40 |           "h-1.5 w-1.5 rounded-full transition-colors duration-500", 
41 |           dotColor,
42 |           animate && "animate-pulse"
43 |         )} 
44 |       />
45 |       <span className="text-[10px] font-medium tracking-widest text-[#86868b] uppercase">
46 |         {text}
47 |       </span>
48 |     </div>
49 |   );
50 | }
51 | 


--------------------------------------------------------------------------------
/frontend/public/vite.svg:
--------------------------------------------------------------------------------
1 | <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>


--------------------------------------------------------------------------------
/logger.py:
--------------------------------------------------------------------------------
 1 | import logging
 2 | from rich.console import Console
 3 | from rich.panel import Panel
 4 | from rich.logging import RichHandler
 5 | from rich.theme import Theme
 6 | 
 7 | # Custom theme for the console
 8 | custom_theme = Theme({
 9 |     "info": "dim cyan",
10 |     "warning": "magenta",
11 |     "error": "bold red",
12 |     "success": "bold green",
13 |     "thought": "italic cyan",
14 |     "code": "bold yellow",
15 |     "result": "white"
16 | })
17 | 
18 | console = Console(theme=custom_theme)
19 | 
20 | def setup_logging():
21 |     """Sets up logging to both file and console."""
22 |     logging.basicConfig(
23 |         level=logging.INFO,
24 |         format="%(asctime)s - %(levelname)s - %(message)s",
25 |         handlers=[
26 |             logging.FileHandler("agent.log"),
27 |             # We don't add RichHandler here because we want manual control over console output
28 |             # to keep it "elegant" and not just a stream of logs.
29 |         ]
30 |     )
31 |     # Create a separate logger for the file that doesn't propagate to root
32 |     file_logger = logging.getLogger("agent_file")
33 |     file_logger.setLevel(logging.DEBUG)
34 |     return file_logger
35 | 
36 | # Global file logger instance
37 | logger = setup_logging()
38 | 
39 | def log_step(step_name, status="INFO"):
40 |     """Logs a step to the file."""
41 |     logger.info(f"[{step_name}] {status}")
42 | 
43 | def print_panel(content, title, style="info"):
44 |     """Prints a rich panel to the console."""
45 |     console.print(Panel(content, title=title, border_style=style, expand=False))
46 | 
47 | def print_status(message, style="info"):
48 |     """Prints a status message."""
49 |     console.print(f"[{style}]{message}[/{style}]")
50 | 


--------------------------------------------------------------------------------
/frontend/src/components/Console.tsx:
--------------------------------------------------------------------------------
 1 | import { useEffect, useRef } from "react";
 2 | import { LogEvent } from "@/lib/api";
 3 | import { cn } from "@/lib/utils";
 4 | 
 5 | interface ConsoleProps {
 6 |   logs: LogEvent[];
 7 |   className?: string;
 8 | }
 9 | 
10 | export function Console({ logs, className }: ConsoleProps) {
11 |   const bottomRef = useRef<HTMLDivElement>(null);
12 | 
13 |   useEffect(() => {
14 |     bottomRef.current?.scrollIntoView({ behavior: "smooth" });
15 |   }, [logs]);
16 | 
17 |   return (
18 |     <div
19 |       className={cn(
20 |         "bg-black border border-border/40 rounded-lg overflow-hidden flex flex-col font-mono text-xs",
21 |         className
22 |       )}
23 |     >
24 |       <div className="px-4 py-2 border-b border-border/40 bg-muted/20 flex items-center justify-between">
25 |         <span className="text-muted-foreground">Console Output</span>
26 |         <div className="flex gap-1.5">
27 |           <div className="w-2.5 h-2.5 rounded-full bg-red-500/20 border border-red-500/50" />
28 |           <div className="w-2.5 h-2.5 rounded-full bg-yellow-500/20 border border-yellow-500/50" />
29 |           <div className="w-2.5 h-2.5 rounded-full bg-green-500/20 border border-green-500/50" />
30 |         </div>
31 |       </div>
32 |       <div className="flex-1 overflow-y-auto p-4 space-y-1 max-h-[300px]">
33 |         {logs.length === 0 && (
34 |           <div className="text-muted-foreground/50 italic">
35 |             Waiting for process output...
36 |           </div>
37 |         )}
38 |         {logs
39 |           .filter((log) => !((log.plain ?? log.raw ?? "").includes("::EVENT::")))
40 |           .map((log, i) => (
41 |             <div key={i} className="whitespace-pre-wrap break-all">
42 |               <span className="text-muted-foreground select-none mr-3">
43 |                 {new Date(log.timestamp).toLocaleTimeString([], {
44 |                   hour12: false,
45 |                   hour: "2-digit",
46 |                   minute: "2-digit",
47 |                   second: "2-digit",
48 |                 })}
49 |               </span>
50 |               <span
51 |                 className={cn(
52 |                   log.stream === "stderr" ? "text-red-400" : "text-zinc-300"
53 |                 )}
54 |               >
55 |                 {log.plain || log.raw}
56 |               </span>
57 |             </div>
58 |           ))}
59 |         <div ref={bottomRef} />
60 |       </div>
61 |     </div>
62 |   );
63 | }
64 | 


--------------------------------------------------------------------------------
/frontend/src/components/StreamingMarkdown.tsx:
--------------------------------------------------------------------------------
 1 | import { useEffect, useState } from "react";
 2 | import ReactMarkdown from "react-markdown";
 3 | import remarkGfm from "remark-gfm";
 4 | import { cn } from "@/lib/utils";
 5 | 
 6 | interface StreamingMarkdownProps {
 7 |     content: string;
 8 |     /**
 9 |      * A key that identifies a logical block of streaming content.
10 |      * When this changes (e.g. new thought / new cell), we restart the animation.
11 |      */
12 |     animateKey?: string | number;
13 |     /**
14 |      * Tailwind / CSS classes applied to the markdown body wrapper.
15 |      */
16 |     markdownClassName?: string;
17 |     /**
18 |      * Optional classes for the outer container (animation wrapper).
19 |      */
20 |     wrapperClassName?: string;
21 | }
22 | 
23 | /**
24 |  * StreamingMarkdown
25 |  *
26 |  * Renders markdown that is being updated incrementally (streamed tokens).
27 |  * Every time the content changes, we softly re-trigger a fade-in animation
28 |  * on the entire block using the global `.stream-fade` styles.
29 |  *
30 |  * This keeps the effect subtle but ensures *all* new streamed chunks
31 |  * participate in the animation, not just the initial thought.
32 |  */
33 | export function StreamingMarkdown({
34 |     content,
35 |     animateKey,
36 |     markdownClassName,
37 |     wrapperClassName,
38 | }: StreamingMarkdownProps) {
39 |     const [isAnimating, setIsAnimating] = useState(false);
40 | 
41 |     useEffect(() => {
42 |         if (typeof window === "undefined") return;
43 | 
44 |         let timeoutId: number | null = null;
45 |         const rafId = window.requestAnimationFrame(() => {
46 |             setIsAnimating(true);
47 |             timeoutId = window.setTimeout(() => setIsAnimating(false), 420); // match CSS duration
48 |         });
49 | 
50 |         return () => {
51 |             window.cancelAnimationFrame(rafId);
52 |             if (timeoutId !== null) window.clearTimeout(timeoutId);
53 |         };
54 |     }, [content, animateKey]);
55 | 
56 |     return (
57 |         <div
58 |             className={cn(
59 |                 "stream-fade",
60 |                 isAnimating && "stream-fade--active",
61 |                 wrapperClassName
62 |             )}
63 |         >
64 |             <div className={markdownClassName}>
65 |                 <ReactMarkdown remarkPlugins={[remarkGfm]}>
66 |                     {content}
67 |                 </ReactMarkdown>
68 |             </div>
69 |         </div>
70 |     );
71 | }
72 | 


--------------------------------------------------------------------------------
/frontend/tailwind.config.js:
--------------------------------------------------------------------------------
 1 | /** @type {import('tailwindcss').Config} */
 2 | export default {
 3 |     content: [
 4 |         "./index.html",
 5 |         "./src/**/*.{js,ts,jsx,tsx}",
 6 |     ],
 7 |     theme: {
 8 |         extend: {
 9 |             colors: {
10 |                 background: "hsl(var(--background))",
11 |                 foreground: "hsl(var(--foreground))",
12 |                 card: {
13 |                     DEFAULT: "hsl(var(--card))",
14 |                     foreground: "hsl(var(--card-foreground))",
15 |                 },
16 |                 popover: {
17 |                     DEFAULT: "hsl(var(--popover))",
18 |                     foreground: "hsl(var(--popover-foreground))",
19 |                 },
20 |                 primary: {
21 |                     DEFAULT: "hsl(var(--primary))",
22 |                     foreground: "hsl(var(--primary-foreground))",
23 |                 },
24 |                 secondary: {
25 |                     DEFAULT: "hsl(var(--secondary))",
26 |                     foreground: "hsl(var(--secondary-foreground))",
27 |                 },
28 |                 muted: {
29 |                     DEFAULT: "hsl(var(--muted))",
30 |                     foreground: "hsl(var(--muted-foreground))",
31 |                 },
32 |                 accent: {
33 |                     DEFAULT: "hsl(var(--accent))",
34 |                     foreground: "hsl(var(--accent-foreground))",
35 |                 },
36 |                 destructive: {
37 |                     DEFAULT: "hsl(var(--destructive))",
38 |                     foreground: "hsl(var(--destructive-foreground))",
39 |                 },
40 |                 border: "hsl(var(--border))",
41 |                 input: "hsl(var(--input))",
42 |                 ring: "hsl(var(--ring))",
43 |                 chart: {
44 |                     "1": "hsl(var(--chart-1))",
45 |                     "2": "hsl(var(--chart-2))",
46 |                     "3": "hsl(var(--chart-3))",
47 |                     "4": "hsl(var(--chart-4))",
48 |                     "5": "hsl(var(--chart-5))",
49 |                 },
50 |             },
51 |             borderRadius: {
52 |                 lg: "var(--radius)",
53 |                 md: "calc(var(--radius) - 2px)",
54 |                 sm: "calc(var(--radius) - 4px)",
55 |             },
56 |             fontFamily: {
57 |                 sans: ['Inter', 'sans-serif'],
58 |                 mono: ['JetBrains Mono', 'monospace'],
59 |                 serif: ['Newsreader', 'serif'],
60 |             },
61 |         },
62 |     },
63 |     plugins: [
64 |         require('@tailwindcss/typography'),
65 |     ],
66 | }
67 | 


--------------------------------------------------------------------------------
/frontend/README.md:
--------------------------------------------------------------------------------
 1 | # React + TypeScript + Vite
 2 | 
 3 | This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
 4 | 
 5 | Currently, two official plugins are available:
 6 | 
 7 | - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
 8 | - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
 9 | 
10 | ## React Compiler
11 | 
12 | The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
13 | 
14 | ## Expanding the ESLint configuration
15 | 
16 | If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
17 | 
18 | ```js
19 | export default defineConfig([
20 |   globalIgnores(['dist']),
21 |   {
22 |     files: ['**/*.{ts,tsx}'],
23 |     extends: [
24 |       // Other configs...
25 | 
26 |       // Remove tseslint.configs.recommended and replace with this
27 |       tseslint.configs.recommendedTypeChecked,
28 |       // Alternatively, use this for stricter rules
29 |       tseslint.configs.strictTypeChecked,
30 |       // Optionally, add this for stylistic rules
31 |       tseslint.configs.stylisticTypeChecked,
32 | 
33 |       // Other configs...
34 |     ],
35 |     languageOptions: {
36 |       parserOptions: {
37 |         project: ['./tsconfig.node.json', './tsconfig.app.json'],
38 |         tsconfigRootDir: import.meta.dirname,
39 |       },
40 |       // other options...
41 |     },
42 |   },
43 | ])
44 | ```
45 | 
46 | You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
47 | 
48 | ```js
49 | // eslint.config.js
50 | import reactX from 'eslint-plugin-react-x'
51 | import reactDom from 'eslint-plugin-react-dom'
52 | 
53 | export default defineConfig([
54 |   globalIgnores(['dist']),
55 |   {
56 |     files: ['**/*.{ts,tsx}'],
57 |     extends: [
58 |       // Other configs...
59 |       // Enable lint rules for React
60 |       reactX.configs['recommended-typescript'],
61 |       // Enable lint rules for React DOM
62 |       reactDom.configs.recommended,
63 |     ],
64 |     languageOptions: {
65 |       parserOptions: {
66 |         project: ['./tsconfig.node.json', './tsconfig.app.json'],
67 |         tsconfigRootDir: import.meta.dirname,
68 |       },
69 |       // other options...
70 |     },
71 |   },
72 | ])
73 | ```
74 | 


--------------------------------------------------------------------------------
/frontend/src/index.css:
--------------------------------------------------------------------------------
  1 | @import "tailwindcss";
  2 | @config "../tailwind.config.js";
  3 | 
  4 | @layer base {
  5 |   :root {
  6 |     --background: 240 10% 3.9%;
  7 |     --foreground: 0 0% 98%;
  8 |     --card: 240 10% 3.9%;
  9 |     --card-foreground: 0 0% 98%;
 10 |     --popover: 240 10% 3.9%;
 11 |     --popover-foreground: 0 0% 98%;
 12 |     --primary: 0 0% 98%;
 13 |     --primary-foreground: 240 5.9% 10%;
 14 |     --secondary: 240 3.7% 15.9%;
 15 |     --secondary-foreground: 0 0% 98%;
 16 |     --muted: 240 3.7% 15.9%;
 17 |     --muted-foreground: 240 5% 64.9%;
 18 |     --accent: 240 3.7% 15.9%;
 19 |     --accent-foreground: 0 0% 98%;
 20 |     --destructive: 0 62.8% 30.6%;
 21 |     --destructive-foreground: 0 0% 98%;
 22 |     --border: 240 3.7% 15.9%;
 23 |     --input: 240 3.7% 15.9%;
 24 |     --ring: 240 4.9% 83.9%;
 25 |     --chart-1: 220 70% 50%;
 26 |     --chart-2: 160 60% 45%;
 27 |     --chart-3: 30 80% 55%;
 28 |     --chart-4: 280 65% 60%;
 29 |     --chart-5: 340 75% 55%;
 30 |     --radius: 0.5rem;
 31 |   }
 32 | }
 33 | 
 34 | @layer base {
 35 |   * {
 36 |     @apply border-border;
 37 |   }
 38 | 
 39 |   body {
 40 |     @apply bg-background text-foreground;
 41 |     font-feature-settings: "rlig" 1, "calt" 1;
 42 |   }
 43 | }
 44 | 
 45 | /* Custom Scrollbar Global (Dark) */
 46 | ::-webkit-scrollbar {
 47 |   width: 8px;
 48 |   height: 8px;
 49 | }
 50 | 
 51 | ::-webkit-scrollbar-track {
 52 |   background: transparent;
 53 | }
 54 | 
 55 | ::-webkit-scrollbar-thumb {
 56 |   @apply bg-muted rounded-full;
 57 | }
 58 | 
 59 | ::-webkit-scrollbar-thumb:hover {
 60 |   @apply bg-muted-foreground/50;
 61 | }
 62 | 
 63 | /* Light Theme Scrollbar override */
 64 | .custom-scrollbar-light::-webkit-scrollbar-thumb {
 65 |   @apply bg-gray-300;
 66 | }
 67 | 
 68 | .custom-scrollbar-light::-webkit-scrollbar-thumb:hover {
 69 |   @apply bg-gray-400;
 70 | }
 71 | 
 72 | /* Print Styles */
 73 | @media print {
 74 |   @page {
 75 |     margin: 0;
 76 |     size: auto;
 77 |   }
 78 | 
 79 |   body * {
 80 |     visibility: hidden;
 81 |   }
 82 | 
 83 |   #printable-paper-content,
 84 |   #printable-paper-content * {
 85 |     visibility: visible;
 86 |   }
 87 | 
 88 |   #printable-paper-content {
 89 |     position: fixed;
 90 |     left: 0;
 91 |     top: 0;
 92 |     width: 100vw;
 93 |     height: auto;
 94 |     margin: 0;
 95 |     padding: 1in;
 96 |     background: white !important;
 97 |     color: black !important;
 98 |     box-shadow: none !important;
 99 |     overflow: visible !important;
100 |     -webkit-print-color-adjust: exact;
101 |     print-color-adjust: exact;
102 |   }
103 |   
104 |   /* Hide footer in print */
105 |   .no-print {
106 |     display: none !important;
107 |   }
108 | }
109 | 
110 | /* Subtle fade for streamed tokens */
111 | .stream-fade {
112 |   will-change: opacity, transform, filter;
113 | }
114 | 
115 | .stream-fade--active {
116 |   animation: streamFade 0.42s ease-out;
117 |   animation-fill-mode: backwards;
118 | }
119 | 
120 | @keyframes streamFade {
121 |   from {
122 |     opacity: 0.2;
123 |     transform: translateY(6px);
124 |     filter: blur(8px);
125 |   }
126 |   65% {
127 |     opacity: 1;
128 |     transform: translateY(0);
129 |     filter: blur(0);
130 |   }
131 |   to {
132 |     opacity: 1;
133 |   }
134 | }
135 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # AI Researcher
 2 | [![Twitter Follow](https://img.shields.io/twitter/follow/mattshumer_?style=social)](https://twitter.com/mattshumer_)
 3 | 
 4 | [Be the first to know when I publish new AI builds + demos!](https://tally.so/r/w2M17p)
 5 | 
 6 | An autonomous AI researcher. It takes a research objective, breaks it into experiments, spins up separate agents with access to their own GPUs to run these experiments, and delivers a paper-style writeup with findings.
 7 | 
 8 | ## How it Works
 9 | - Decomposes your prompt into experiments and assigns them to specialist researcher agents.
10 | - Each agent can launch GPU-enabled sandboxes to train models/run inference/etc., evaluate, and collect evidence.
11 | - Based on the results of these experiments, the orchestrator can decide to finalize, or run more experiments.
12 | - The orchestrator goes over all of the results and turns them into a coherent "paper".
13 | 
14 | ## Run it (web notebook, one command)
15 | The fastest way to use it:
16 | ```
17 | python run_app.py
18 | ```
19 | This installs missing deps, starts the API + frontend, and opens the notebook. If Google/Modal keys aren’t set, the UI will prompt you and save them locally before the run starts.
20 | 
21 | ## Keys Needed
22 | - **LLM key** (at least one):
23 |   - Google AI Studio: `GOOGLE_API_KEY` (for Gemini 3 Pro)
24 |   - Anthropic: `ANTHROPIC_API_KEY` (for Claude Opus 4.5)
25 | - **Modal tokens**: `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` (for GPU sandboxes)
26 | - Add them to `.env` in the repo root, or paste them into the web prompt when asked.
27 | 
28 | ## Model Selection
29 | Choose between **Gemini 3 Pro** and **Claude Opus 4.5** from the dropdown in the web UI, or via CLI with `--model`.
30 | 
31 | ## Optional CLI
32 | Prefer the terminal?
33 | ```
34 | python -m venv venv && source venv/bin/activate
35 | pip install -r requirements.txt
36 | python main.py "Does label smoothing improve ViT-Base on CIFAR-10?" --mode single --gpu any --model gemini-3-pro-preview
37 | ```
38 | Orchestrator (multi-agent):
39 | ```
40 | python main.py "Characterize scaling laws for sparse attention transformers" \
41 |   --mode orchestrator --num-agents 3 --max-rounds 3 --max-parallel 2 --gpu any
42 | ```
43 | Dry run:
44 | ```
45 | python main.py "Sanity check the pipeline" --mode orchestrator --test-mode
46 | ```
47 | 
48 | ## Deploy to Railway
49 | 
50 | [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template?template=https://github.com/mattshumer/ai-researcher&referralCode=mattshumer)
51 | 
52 | **Steps:**
53 | 1. Click the button above (or go to Railway and select "Deploy from GitHub repo")
54 | 2. Connect your GitHub account and select this repo (or your fork)
55 | 3. Railway will automatically detect the Dockerfile and build the app
56 | 4. Once deployed, open the app URL and enter your API keys in the UI
57 | 
58 | **Optional environment variables** (if you want server-side defaults):
59 | - `GOOGLE_API_KEY` - Google AI Studio key for Gemini 3 Pro
60 | - `ANTHROPIC_API_KEY` - Anthropic key for Claude Opus 4.5
61 | - `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` - For GPU sandboxes
62 | 
63 | Note: Users can also enter their own keys directly in the web UI without setting environment variables.
64 | 
65 | ## Status/Contribution
66 | This is a super-early, experimental harness. There are a number of improvements to be worked out (i.e. dataset sharing between agents, key management, etc.), literature search, that would make this way more capable. If anyone wants to add these in, feel free!


--------------------------------------------------------------------------------
/frontend/src/assets/react.svg:
--------------------------------------------------------------------------------
1 | <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="35.93" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 228"><path fill="#00D8FF" d="M210.483 73.824a171.49 171.49 0 0 0-8.24-2.597c.465-1.9.893-3.777 1.273-5.621c6.238-30.281 2.16-54.676-11.769-62.708c-13.355-7.7-35.196.329-57.254 19.526a171.23 171.23 0 0 0-6.375 5.848a155.866 155.866 0 0 0-4.241-3.917C100.759 3.829 77.587-4.822 63.673 3.233C50.33 10.957 46.379 33.89 51.995 62.588a170.974 170.974 0 0 0 1.892 8.48c-3.28.932-6.445 1.924-9.474 2.98C17.309 83.498 0 98.307 0 113.668c0 15.865 18.582 31.778 46.812 41.427a145.52 145.52 0 0 0 6.921 2.165a167.467 167.467 0 0 0-2.01 9.138c-5.354 28.2-1.173 50.591 12.134 58.266c13.744 7.926 36.812-.22 59.273-19.855a145.567 145.567 0 0 0 5.342-4.923a168.064 168.064 0 0 0 6.92 6.314c21.758 18.722 43.246 26.282 56.54 18.586c13.731-7.949 18.194-32.003 12.4-61.268a145.016 145.016 0 0 0-1.535-6.842c1.62-.48 3.21-.974 4.76-1.488c29.348-9.723 48.443-25.443 48.443-41.52c0-15.417-17.868-30.326-45.517-39.844Zm-6.365 70.984c-1.4.463-2.836.91-4.3 1.345c-3.24-10.257-7.612-21.163-12.963-32.432c5.106-11 9.31-21.767 12.459-31.957c2.619.758 5.16 1.557 7.61 2.4c23.69 8.156 38.14 20.213 38.14 29.504c0 9.896-15.606 22.743-40.946 31.14Zm-10.514 20.834c2.562 12.94 2.927 24.64 1.23 33.787c-1.524 8.219-4.59 13.698-8.382 15.893c-8.067 4.67-25.32-1.4-43.927-17.412a156.726 156.726 0 0 1-6.437-5.87c7.214-7.889 14.423-17.06 21.459-27.246c12.376-1.098 24.068-2.894 34.671-5.345a134.17 134.17 0 0 1 1.386 6.193ZM87.276 214.515c-7.882 2.783-14.16 2.863-17.955.675c-8.075-4.657-11.432-22.636-6.853-46.752a156.923 156.923 0 0 1 1.869-8.499c10.486 2.32 22.093 3.988 34.498 4.994c7.084 9.967 14.501 19.128 21.976 27.15a134.668 134.668 0 0 1-4.877 4.492c-9.933 8.682-19.886 14.842-28.658 17.94ZM50.35 144.747c-12.483-4.267-22.792-9.812-29.858-15.863c-6.35-5.437-9.555-10.836-9.555-15.216c0-9.322 13.897-21.212 37.076-29.293c2.813-.98 5.757-1.905 8.812-2.773c3.204 10.42 7.406 21.315 12.477 32.332c-5.137 11.18-9.399 22.249-12.634 32.792a134.718 134.718 0 0 1-6.318-1.979Zm12.378-84.26c-4.811-24.587-1.616-43.134 6.425-47.789c8.564-4.958 27.502 2.111 47.463 19.835a144.318 144.318 0 0 1 3.841 3.545c-7.438 7.987-14.787 17.08-21.808 26.988c-12.04 1.116-23.565 2.908-34.161 5.309a160.342 160.342 0 0 1-1.76-7.887Zm110.427 27.268a347.8 347.8 0 0 0-7.785-12.803c8.168 1.033 15.994 2.404 23.343 4.08c-2.206 7.072-4.956 14.465-8.193 22.045a381.151 381.151 0 0 0-7.365-13.322Zm-45.032-43.861c5.044 5.465 10.096 11.566 15.065 18.186a322.04 322.04 0 0 0-30.257-.006c4.974-6.559 10.069-12.652 15.192-18.18ZM82.802 87.83a323.167 323.167 0 0 0-7.227 13.238c-3.184-7.553-5.909-14.98-8.134-22.152c7.304-1.634 15.093-2.97 23.209-3.984a321.524 321.524 0 0 0-7.848 12.897Zm8.081 65.352c-8.385-.936-16.291-2.203-23.593-3.793c2.26-7.3 5.045-14.885 8.298-22.6a321.187 321.187 0 0 0 7.257 13.246c2.594 4.48 5.28 8.868 8.038 13.147Zm37.542 31.03c-5.184-5.592-10.354-11.779-15.403-18.433c4.902.192 9.899.29 14.978.29c5.218 0 10.376-.117 15.453-.343c-4.985 6.774-10.018 12.97-15.028 18.486Zm52.198-57.817c3.422 7.8 6.306 15.345 8.596 22.52c-7.422 1.694-15.436 3.058-23.88 4.071a382.417 382.417 0 0 0 7.859-13.026a347.403 347.403 0 0 0 7.425-13.565Zm-16.898 8.101a358.557 358.557 0 0 1-12.281 19.815a329.4 329.4 0 0 1-23.444.823c-7.967 0-15.716-.248-23.178-.732a310.202 310.202 0 0 1-12.513-19.846h.001a307.41 307.41 0 0 1-10.923-20.627a310.278 310.278 0 0 1 10.89-20.637l-.001.001a307.318 307.318 0 0 1 12.413-19.761c7.613-.576 15.42-.876 23.31-.876H128c7.926 0 15.743.303 23.354.883a329.357 329.357 0 0 1 12.335 19.695a358.489 358.489 0 0 1 11.036 20.54a329.472 329.472 0 0 1-11 20.722Zm22.56-122.124c8.572 4.944 11.906 24.881 6.52 51.026c-.344 1.668-.73 3.367-1.15 5.09c-10.622-2.452-22.155-4.275-34.23-5.408c-7.034-10.017-14.323-19.124-21.64-27.008a160.789 160.789 0 0 1 5.888-5.4c18.9-16.447 36.564-22.941 44.612-18.3ZM128 90.808c12.625 0 22.86 10.235 22.86 22.86s-10.235 22.86-22.86 22.86s-22.86-10.235-22.86-22.86s10.235-22.86 22.86-22.86Z"></path></svg>


--------------------------------------------------------------------------------
/frontend/src/components/Notebook/NotebookCell.tsx:
--------------------------------------------------------------------------------
 1 | import { Terminal, ArrowRight } from "lucide-react";
 2 | import { ExperimentStep } from "@/lib/useExperiment";
 3 | import { StreamingMarkdown } from "../StreamingMarkdown";
 4 | 
 5 | interface NotebookCellProps {
 6 |     step: ExperimentStep;
 7 | }
 8 | 
 9 | export function NotebookCell({ step }: NotebookCellProps) {
10 |     const { type, content, id } = step;
11 | 
12 |     if (type === "thought") {
13 |         return (
14 |             <div className="animate-in fade-in slide-in-from-bottom-2 duration-500">
15 |                 <div className="flex items-center gap-2 mb-2">
16 |                     <div className="w-1 h-1 rounded-full bg-[#424245]" />
17 |                     <span className="text-[10px] font-medium text-[#424245] uppercase tracking-widest">Thinking</span>
18 |                 </div>
19 |                 <div className="pl-3 border-l border-[#1d1d1f] ml-0.5">
20 |                     <StreamingMarkdown
21 |                         animateKey={id}
22 |                         content={content}
23 |                         markdownClassName="prose prose-invert prose-sm max-w-none prose-p:text-[#86868b] prose-p:text-xs prose-p:leading-relaxed prose-p:font-light prose-headings:text-[#d1d1d6] prose-strong:text-[#d1d1d6] prose-code:text-[#d1d1d6] prose-pre:bg-[#1d1d1f] prose-pre:border prose-pre:border-[#333] [&>*:first-child]:mt-0"
24 |                     />
25 |                 </div>
26 |             </div>
27 |         );
28 |     }
29 | 
30 |     if (type === "code") {
31 |         return (
32 |             <div className="animate-in fade-in slide-in-from-bottom-2 duration-500">
33 |                 <div className="flex items-center gap-2 mb-2">
34 |                     <Terminal className="w-3 h-3 text-[#424245]" />
35 |                     <span className="text-[10px] font-medium text-[#424245] uppercase tracking-widest">Command</span>
36 |                 </div>
37 |                 <div className="bg-[#0a0a0a] border border-[#1d1d1f] rounded-sm overflow-hidden">
38 |                     <pre className="p-3 text-[10px] font-mono text-[#d1d1d6] overflow-x-auto custom-scrollbar">
39 |                         {content}
40 |                     </pre>
41 |                 </div>
42 |             </div>
43 |         );
44 |     }
45 | 
46 |     if (type === "result") {
47 |         // Handle carriage returns (\r) for progress bars (like tqdm).
48 |         // We want to simulate the terminal behavior where \r moves the cursor 
49 |         // to the start of the line, allowing subsequent text to overwrite.
50 |         // We split by \r and take the last segment for the current line context if it's a pure overwrite,
51 |         // but \r can be mixed with \n.
52 |         // A simple approximation is: split by \n, and for each line, process \r.
53 |         
54 |         const processCarriageReturns = (text: string) => {
55 |             const lines = text.split('\n');
56 |             const processedLines = lines.map(line => {
57 |                 // If line has \r, usually we just want the text AFTER the last \r
58 |                 // unless that \r is followed by nothing? 
59 |                 // Standard terminal: "Loading... 10%\rLoading... 20%" -> "Loading... 20%"
60 |                 // "Item 1\rItem 2" -> "Item 2"
61 |                 
62 |                 if (line.includes('\r')) {
63 |                     const parts = line.split('\r');
64 |                     return parts[parts.length - 1];
65 |                 }
66 |                 return line;
67 |             });
68 |             return processedLines.join('\n');
69 |         };
70 | 
71 |         return (
72 |             <div className="animate-in fade-in slide-in-from-bottom-2 duration-500">
73 |                 <div className="flex items-center gap-2 mb-2">
74 |                     <ArrowRight className="w-3 h-3 text-[#424245]" />
75 |                     <span className="text-[10px] font-medium text-[#424245] uppercase tracking-widest">Output</span>
76 |                 </div>
77 |                 <div className="pl-3 border-l border-[#1d1d1f] ml-0.5">
78 |                     <pre className="text-[10px] font-mono text-[#86868b] overflow-x-auto custom-scrollbar whitespace-pre-wrap">
79 |                         {processCarriageReturns(content)}
80 |                     </pre>
81 |                 </div>
82 |             </div>
83 |         );
84 |     }
85 | 
86 |     return null;
87 | }
88 | 


--------------------------------------------------------------------------------
/modal_guide.md:
--------------------------------------------------------------------------------
  1 | # Modal Guide for AI Agents
  2 | 
  3 | This guide provides a concise, accurate reference for using Modal to spin up GPUs, run code, track costs, and manage data.
  4 | 
  5 | ## 1. Core Concepts
  6 | - **App**: The unit of deployment. Defined as `app = modal.App("my-app-name")`.
  7 | - **Image**: The environment (OS + Python packages).
  8 | - **Function**: The code that runs remotely. Decorated with `@app.function`.
  9 | - **Volume**: Persistent storage for large files (datasets, models).
 10 | 
 11 | ## 2. Project Structure
 12 | A standard Modal project is a single Python file (e.g., `experiment.py`) or a module.
 13 | 
 14 | ```python
 15 | import modal
 16 | 
 17 | app = modal.App("experiment-01")
 18 | 
 19 | # Define the environment
 20 | image = (
 21 |     modal.Image.debian_slim()
 22 |     .pip_install("torch", "transformers", "numpy")
 23 | )
 24 | 
 25 | @app.function(image=image, gpu="A100")
 26 | def run_experiment(params: dict):
 27 |     import torch
 28 |     print(f"Running on {torch.cuda.get_device_name(0)}")
 29 |     # ... experiment logic ...
 30 |     return {"status": "success", "loss": 0.01}
 31 | 
 32 | @app.local_entrypoint()
 33 | def main():
 34 |     print("Starting remote experiment...")
 35 |     result = run_experiment.remote({"learning_rate": 0.001})
 36 |     print(f"Result: {result}")
 37 | ```
 38 | 
 39 | ## 3. Spinning Up GPUs
 40 | Specify the `gpu` argument in the `@app.function` decorator.
 41 | 
 42 | ### GPU Types
 43 | - **H100**: `gpu="H100"` (Most powerful, scarce)
 44 | - **A100**: `gpu="A100"` (Standard for LLM training/inference)
 45 |     - `gpu="A100-80GB"` (Force 80GB memory)
 46 | - **A10G**: `gpu="A10G"` (Good price/performance for inference)
 47 | - **T4**: `gpu="T4"` (Cheap, older)
 48 | - **Any**: `gpu="any"` (Lowest availability latency)
 49 | 
 50 | ### Multi-GPU
 51 | Append `:N` to the type string.
 52 | ```python
 53 | @app.function(gpu="A100:4") # Request 4 A100s
 54 | ```
 55 | 
 56 | ## 4. Persistent Storage (Volumes)
 57 | Use `modal.Volume` to persist data across runs.
 58 | 
 59 | ### Creating & Mounting
 60 | ```python
 61 | # Create/Get volume
 62 | volume = modal.Volume.from_name("my-dataset-vol", create_if_missing=True)
 63 | 
 64 | @app.function(volumes={"/data": volume})
 65 | def process_data():
 66 |     # Read
 67 |     with open("/data/input.txt", "r") as f:
 68 |         data = f.read()
 69 |     
 70 |     # Write
 71 |     with open("/data/output.txt", "w") as f:
 72 |         f.write("processed")
 73 |     
 74 |     # CRITICAL: Commit changes to persist them!
 75 |     volume.commit() 
 76 | ```
 77 | 
 78 | ### Reloading
 79 | If another function updates the volume, reload it to see changes:
 80 | ```python
 81 | volume.reload()
 82 | ```
 83 | 
 84 | ## 5. Secrets & API Keys
 85 | Inject environment variables securely.
 86 | 
 87 | 1.  **Create Secret** (CLI or Dashboard):
 88 |     `modal secret create my-huggingface-secret HF_TOKEN=hf_...`
 89 | 
 90 | 2.  **Use in Code**:
 91 | ```python
 92 | @app.function(secrets=[modal.Secret.from_name("my-huggingface-secret")])
 93 | def download_model():
 94 |     import os
 95 |     token = os.environ["HF_TOKEN"]
 96 | ```
 97 | 
 98 | ## 6. Running Code
 99 | ### CLI
100 | Run the local entrypoint:
101 | ```bash
102 | modal run experiment.py
103 | ```
104 | 
105 | ### Remote Execution
106 | - **`func.remote(args)`**: Synchronous call. Returns the result.
107 | - **`func.spawn(args)`**: Asynchronous call. Returns a `FunctionCall` object.
108 |     ```python
109 |     job = run_experiment.spawn(params)
110 |     # ... do other work ...
111 |     result = job.get()
112 |     ```
113 | 
114 | ## 7. Web Endpoints
115 | Expose a function as a web endpoint (useful for agent-to-agent communication).
116 | 
117 | ```python
118 | @app.function()
119 | @modal.web_endpoint(method="POST")
120 | def webhook(data: dict):
121 |     return {"received": data}
122 | ```
123 | *URL is printed to stdout on deploy.*
124 | 
125 | ## 8. Observability & Costs
126 | ### Logs
127 | - **Live**: Streamed to your terminal during `modal run`.
128 | - **Dashboard**: View full logs at `https://modal.com/apps`.
129 | - **Programmatic**: Currently, logs are best consumed via the dashboard or by redirecting stdout in the function to a file on a Volume.
130 | 
131 | ### Cost Tracking
132 | - **Pricing**: Usage-based (per second).
133 |     - A100: ~$0.000694/sec
134 |     - H100: ~$0.001097/sec
135 |     - CPU: Very cheap
136 | - **Dashboard**: View "Usage & Billing" in the Modal dashboard for exact costs per app/function.
137 | - **Optimization**:
138 |     - Use `modal.Image` caching (builds are cached).
139 |     - Scale down to 0 automatically (serverless).
140 | 
141 | ## 9. Quick Reference Checklist
142 | - [ ] **Decorator**: `@app.function(image=..., gpu=..., volumes=..., secrets=...)`
143 | - [ ] **Entrypoint**: `@app.local_entrypoint()`
144 | - [ ] **Run**: `modal run file.py`
145 | - [ ] **Persist**: `volume.commit()` after writes.
146 | - [ ] **Secrets**: `modal.Secret.from_name("name")`
147 | 


--------------------------------------------------------------------------------
/run_app.py:
--------------------------------------------------------------------------------
  1 | import subprocess
  2 | import sys
  3 | import time
  4 | import webbrowser
  5 | import os
  6 | import signal
  7 | from pathlib import Path
  8 | 
  9 | def print_status(msg, color="white"):
 10 |     # ANSI colors
 11 |     colors = {
 12 |         "white": "\033[97m",
 13 |         "cyan": "\033[96m",
 14 |         "green": "\033[92m",
 15 |         "yellow": "\033[93m",
 16 |         "red": "\033[91m",
 17 |         "magenta": "\033[95m",
 18 |     }
 19 |     end = "\033[0m"
 20 |     print(f"{colors.get(color, colors['white'])}[{color.upper()}] {msg}{end}")
 21 | 
 22 | def kill_port(port):
 23 |     """Kill any process listening on the specified port."""
 24 |     try:
 25 |         # Find PID using lsof
 26 |         result = subprocess.run(
 27 |             ["lsof", "-t", "-i", f":{port}"],
 28 |             capture_output=True,
 29 |             text=True
 30 |         )
 31 |         pids = result.stdout.strip().split('\n')
 32 |         
 33 |         for pid in pids:
 34 |             if pid:
 35 |                 print_status(f"Killing existing process on port {port} (PID: {pid})...", "yellow")
 36 |                 subprocess.run(["kill", "-9", pid], check=False)
 37 |     except Exception as e:
 38 |         # lsof might not be installed or other error, just ignore
 39 |         pass
 40 | 
 41 | def ensure_venv(root_dir):
 42 |     """Ensure a virtual environment exists and is used."""
 43 |     venv_dir = root_dir / "venv"
 44 |     venv_python = venv_dir / "bin" / "python"
 45 |     
 46 |     # If we are already running in the venv, continue
 47 |     if sys.prefix == str(venv_dir):
 48 |         return sys.executable
 49 | 
 50 |     print_status("Checking environment...", "cyan")
 51 |     
 52 |     # Create venv if it doesn't exist
 53 |     if not venv_dir.exists():
 54 |         print_status("Creating virtual environment...", "yellow")
 55 |         subprocess.run([sys.executable, "-m", "venv", "venv"], cwd=root_dir, check=True)
 56 |         
 57 |         # Install requirements
 58 |         print_status("Installing backend dependencies...", "yellow")
 59 |         subprocess.run([str(venv_python), "-m", "pip", "install", "-r", "requirements.txt"], cwd=root_dir, check=True)
 60 |     
 61 |     # Re-execute this script using the venv python
 62 |     print_status("Switching to virtual environment...", "cyan")
 63 |     os.execv(str(venv_python), [str(venv_python)] + sys.argv)
 64 | 
 65 | def main():
 66 |     # Paths
 67 |     root_dir = Path(__file__).parent.resolve()
 68 |     frontend_dir = root_dir / "frontend"
 69 |     
 70 |     # 0. Ensure Venv
 71 |     ensure_venv(root_dir)
 72 |     
 73 |     # 1. Cleanup Ports
 74 |     kill_port(8000)
 75 |     kill_port(5173)
 76 |     
 77 |     # 2. Install Frontend Dependencies if needed
 78 |     if not (frontend_dir / "node_modules").exists():
 79 |         print_status("Installing frontend dependencies...", "cyan")
 80 |         subprocess.run(["npm", "install"], cwd=frontend_dir, check=True)
 81 |     
 82 |     # 3. Start Backend
 83 |     print_status("Starting Backend API...", "green")
 84 |     backend_env = os.environ.copy()
 85 |     # Ensure backend sees the venv
 86 |     backend_env["VIRTUAL_ENV"] = str(root_dir / "venv")
 87 |     backend_env["PATH"] = f"{root_dir}/venv/bin:{backend_env['PATH']}"
 88 |     
 89 |     backend_process = subprocess.Popen(
 90 |         [sys.executable, "api_server.py"],
 91 |         cwd=root_dir,
 92 |         env=backend_env
 93 |     )
 94 |     
 95 |     # 4. Start Frontend
 96 |     print_status("Starting Frontend Dev Server...", "green")
 97 |     frontend_process = subprocess.Popen(
 98 |         ["npm", "run", "dev", "--", "--port", "5173"],
 99 |         cwd=frontend_dir,
100 |         stdout=subprocess.PIPE,
101 |         stderr=subprocess.PIPE,
102 |         text=True
103 |     )
104 |     
105 |     # Wait a bit for servers to spin up
106 |     time.sleep(3)
107 |     
108 |     # 5. Open Browser
109 |     print_status("Opening Fractal Notebook...", "magenta")
110 |     webbrowser.open("http://localhost:5173")
111 |     
112 |     print_status("System Running. Press Ctrl+C to stop.", "cyan")
113 |     
114 |     try:
115 |         while True:
116 |             time.sleep(1)
117 |             if backend_process.poll() is not None:
118 |                 print_status("Backend process exited unexpectedly.", "red")
119 |                 break
120 |             if frontend_process.poll() is not None:
121 |                 print_status("Frontend process exited unexpectedly.", "red")
122 |                 # Print frontend error if it failed
123 |                 if frontend_process.stderr:
124 |                     print(frontend_process.stderr.read())
125 |                 break
126 |     except KeyboardInterrupt:
127 |         print_status("\nStopping system...", "yellow")
128 |     finally:
129 |         backend_process.terminate()
130 |         frontend_process.terminate()
131 |         try:
132 |             backend_process.wait(timeout=5)
133 |             frontend_process.wait(timeout=5)
134 |         except subprocess.TimeoutExpired:
135 |             backend_process.kill()
136 |             frontend_process.kill()
137 |         print_status("Shutdown complete.", "green")
138 | 
139 | if __name__ == "__main__":
140 |     main()
141 | 


--------------------------------------------------------------------------------
/main.py:
--------------------------------------------------------------------------------
  1 | import os
  2 | import sys
  3 | import argparse
  4 | from dotenv import load_dotenv
  5 | 
  6 | from agent import run_experiment_loop
  7 | from logger import print_status
  8 | 
  9 | 
 10 | def main():
 11 |     # Load environment variables from .env file
 12 |     load_dotenv()
 13 | 
 14 |     # Debug: show which credentials are available
 15 |     import sys
 16 |     google_key = os.environ.get("GOOGLE_API_KEY", "")
 17 |     anthropic_key = os.environ.get("ANTHROPIC_API_KEY", "")
 18 |     modal_id = os.environ.get("MODAL_TOKEN_ID", "")
 19 |     modal_secret = os.environ.get("MODAL_TOKEN_SECRET", "")
 20 |     print(f"[DEBUG] Credentials check: GOOGLE_API_KEY={'set' if google_key else 'missing'} (len={len(google_key)}), "
 21 |           f"ANTHROPIC_API_KEY={'set' if anthropic_key else 'missing'}, "
 22 |           f"MODAL_TOKEN={'set' if modal_id and modal_secret else 'missing'}", file=sys.stderr)
 23 | 
 24 |     parser = argparse.ArgumentParser(
 25 |         description="AI Experiment Agent CLI (single-agent and orchestrator modes)"
 26 |     )
 27 |     parser.add_argument(
 28 |         "task",
 29 |         type=str,
 30 |         help=(
 31 |             "In 'single' mode: the hypothesis to verify.\n"
 32 |             "In 'orchestrator' mode: the high-level research task to investigate."
 33 |         ),
 34 |     )
 35 |     parser.add_argument(
 36 |         "--gpu",
 37 |         type=str,
 38 |         default=None,
 39 |         help="GPU type to request (e.g., 'T4', 'A10G', 'A100', 'any').",
 40 |     )
 41 |     parser.add_argument(
 42 |         "--mode",
 43 |         type=str,
 44 |         choices=["single", "orchestrator"],
 45 |         default="single",
 46 |         help=(
 47 |             "Execution mode: "
 48 |             "'single' runs a single-researcher agent (original behavior); "
 49 |             "'orchestrator' runs the higher-level multi-agent orchestrator."
 50 |         ),
 51 |     )
 52 |     parser.add_argument(
 53 |         "--num-agents",
 54 |         type=int,
 55 |         default=3,
 56 |         help="(orchestrator) Number of initial single-researcher agents to launch.",
 57 |     )
 58 |     parser.add_argument(
 59 |         "--max-rounds",
 60 |         type=int,
 61 |         default=3,
 62 |         help="(orchestrator) Maximum number of orchestration rounds.",
 63 |     )
 64 |     parser.add_argument(
 65 |         "--max-parallel",
 66 |         type=int,
 67 |         default=2,
 68 |         help=(
 69 |             "(orchestrator) Maximum number of experiments to run in parallel "
 70 |             "in a single wave of tool calls."
 71 |         ),
 72 |     )
 73 |     parser.add_argument(
 74 |         "--test-mode",
 75 |         action="store_true",
 76 |         help="Run in test mode with mock data (no LLM/GPU usage).",
 77 |     )
 78 |     parser.add_argument(
 79 |         "--model",
 80 |         type=str,
 81 |         choices=["gemini-3-pro-preview", "claude-opus-4-5"],
 82 |         default="gemini-3-pro-preview",
 83 |         help=(
 84 |             "LLM model to use: "
 85 |             "'gemini-3-pro-preview' (default) or 'claude-opus-4-5'."
 86 |         ),
 87 |     )
 88 | 
 89 |     args = parser.parse_args()
 90 | 
 91 |     # Preserve existing behavior by default: single agent mode.
 92 |     if args.mode == "single":
 93 |         print_status("Initializing Single Researcher Agent...", "bold cyan")
 94 | 
 95 |         try:
 96 |             # Record GPU preference globally for sandbox creation
 97 |             import agent as agent_module
 98 | 
 99 |             agent_module._selected_gpu = args.gpu
100 |             run_experiment_loop(args.task, test_mode=args.test_mode, model=args.model)
101 |         except KeyboardInterrupt:
102 |             print_status("\nExperiment interrupted by user.", "bold red")
103 |             sys.exit(0)
104 |         except Exception as e:
105 |             import traceback
106 |             print_status(f"\nFatal Error: {e}", "bold red")
107 |             print(f"[ERROR] Fatal Error: {e}", file=sys.stderr)
108 |             traceback.print_exc(file=sys.stderr)
109 |             sys.exit(1)
110 |     else:
111 |         # Multi-agent orchestrator mode.
112 |         print_status("Initializing Orchestrator Agent...", "bold cyan")
113 | 
114 |         try:
115 |             from orchestrator import run_orchestrator_loop
116 | 
117 |             run_orchestrator_loop(
118 |                 research_task=args.task,
119 |                 num_initial_agents=args.num_agents,
120 |                 max_rounds=args.max_rounds,
121 |                 default_gpu=args.gpu,
122 |                 max_parallel_experiments=args.max_parallel,
123 |                 test_mode=args.test_mode,
124 |                 model=args.model,
125 |             )
126 |         except KeyboardInterrupt:
127 |             print_status("\nOrchestrated experiment interrupted by user.", "bold red")
128 |             sys.exit(0)
129 |         except Exception as e:
130 |             import traceback
131 |             print_status(f"\nFatal Error (orchestrator mode): {e}", "bold red")
132 |             print(f"[ERROR] Fatal Error (orchestrator): {e}", file=sys.stderr)
133 |             traceback.print_exc(file=sys.stderr)
134 |             sys.exit(1)
135 | 
136 | 
137 | if __name__ == "__main__":
138 |     main()
139 | 


--------------------------------------------------------------------------------
/gemini_3_pro_guide.md:
--------------------------------------------------------------------------------
  1 | # Gemini 3 Pro: The Complete Developer's Guide
  2 | 
  3 | Gemini 3 Pro is Google's most advanced AI model, featuring state-of-the-art reasoning capabilities. This guide covers everything you need to build agents, run the model, and track costs using the `google-genai` SDK.
  4 | 
  5 | ## 1. Setup
  6 | 
  7 | To use Gemini 3 Pro, you must use the `google-genai` SDK (version 1.51.0 or higher).
  8 | 
  9 | ```bash
 10 | pip install -U google-genai
 11 | ```
 12 | 
 13 | Get your API key from [Google AI Studio](https://aistudio.google.com/).
 14 | 
 15 | ## 2. Running the Model
 16 | 
 17 | Gemini 3 Pro introduces a new parameter: `thinking_level`. This controls the depth of the model's internal reasoning process.
 18 | 
 19 | *   **`high`** (Default): Maximum reasoning depth. Best for complex tasks, coding, and math. Higher latency and cost.
 20 | *   **`low`**: Faster, lower cost. Good for simple instruction following and chat.
 21 | 
 22 | > [!IMPORTANT]
 23 | > You cannot disable "thinking" completely for Gemini 3 Pro.
 24 | 
 25 | ### Basic Example
 26 | 
 27 | ```python
 28 | from google import genai
 29 | from google.genai import types
 30 | import os
 31 | 
 32 | client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
 33 | 
 34 | response = client.models.generate_content(
 35 |     model="gemini-3-pro-preview",
 36 |     contents="Explain the concept of quantum entanglement to a 5-year-old.",
 37 |     config=types.GenerateContentConfig(
 38 |         thinking_level="HIGH", # Options: "LOW", "HIGH" (default)
 39 |     )
 40 | )
 41 | 
 42 | print(response.text)
 43 | ```
 44 | 
 45 | ## 3. Building an Agent (Tool Use)
 46 | 
 47 | Gemini 3 Pro supports advanced tool use (function calling). You define Python functions, pass them to the model, and the model decides when to call them.
 48 | 
 49 | ### Step-by-Step Agent Example
 50 | 
 51 | ```python
 52 | from google import genai
 53 | from google.genai import types
 54 | import os
 55 | 
 56 | # 1. Define the tools
 57 | def get_weather(location: str):
 58 |     """Get the current weather for a given location."""
 59 |     # In a real app, call a weather API here
 60 |     return {"location": location, "temperature": "72", "condition": "Sunny"}
 61 | 
 62 | def get_stock_price(ticker: str):
 63 |     """Get the current stock price for a given ticker symbol."""
 64 |     # In a real app, call a stock API here
 65 |     return {"ticker": ticker, "price": "150.25", "currency": "USD"}
 66 | 
 67 | # 2. Initialize Client
 68 | client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
 69 | 
 70 | # 3. Create the tool configuration
 71 | tools = [get_weather, get_stock_price]
 72 | 
 73 | # 4. Run the model with tools
 74 | response = client.models.generate_content(
 75 |     model="gemini-3-pro-preview",
 76 |     contents="What's the weather in New York and how is Google's stock doing?",
 77 |     config=types.GenerateContentConfig(
 78 |         tools=tools,
 79 |         thinking_level="HIGH" 
 80 |     )
 81 | )
 82 | 
 83 | # 5. Handle the response (Automatic function calling is handled by the SDK in many cases, 
 84 | # but here is how you inspect the tool calls if you need to execute them manually or debug)
 85 | for part in response.candidates[0].content.parts:
 86 |     if part.function_call:
 87 |         print(f"Model requested tool: {part.function_call.name}")
 88 |         print(f"Arguments: {part.function_call.args}")
 89 |         
 90 |         # Execute the tool (simplified logic)
 91 |         tool_name = part.function_call.name
 92 |         tool_args = part.function_call.args
 93 |         
 94 |         if tool_name == "get_weather":
 95 |             result = get_weather(**tool_args)
 96 |         elif tool_name == "get_stock_price":
 97 |             result = get_stock_price(**tool_args)
 98 |             
 99 |         print(f"Tool Result: {result}")
100 | ```
101 | 
102 | > [!TIP]
103 | > For a fully autonomous agent, you would feed the tool results back into the model in a loop until the model generates a final text response.
104 | 
105 | ## 4. Cost Tracking & Pricing
106 | 
107 | Gemini 3 Pro pricing is token-based. To track costs accurately, you must inspect the `usage_metadata` in the response.
108 | 
109 | ### Pricing (Preview Rates)
110 | *   **Input**: ~$2.00 / 1 million tokens (for prompts < 200k tokens)
111 | *   **Output**: ~$12.00 / 1 million tokens (for prompts < 200k tokens)
112 | 
113 | *Note: Prices increase for context windows > 200k tokens. Always check the [official pricing page](https://ai.google.dev/pricing) for the latest numbers.*
114 | 
115 | ### Tracking Tokens Programmatically
116 | 
117 | The response object contains a detailed breakdown of token usage, including the new `thoughts_token_count`.
118 | 
119 | ```python
120 | # ... after generating response ...
121 | 
122 | usage = response.usage_metadata
123 | 
124 | print(f"Input Tokens: {usage.prompt_token_count}")
125 | print(f"Output Tokens (Candidates): {usage.candidates_token_count}")
126 | print(f"Thinking Tokens: {usage.thoughts_token_count}") 
127 | print(f"Total Tokens: {usage.total_token_count}")
128 | 
129 | # Simple Cost Calculator (Estimation)
130 | input_cost = (usage.prompt_token_count / 1_000_000) * 2.00
131 | output_cost = (usage.total_token_count - usage.prompt_token_count) / 1_000_000 * 12.00 # Note: Thinking tokens are billed as output
132 | total_cost = input_cost + output_cost
133 | 
134 | print(f"Estimated Cost: ${total_cost:.6f}")
135 | ```
136 | 
137 | > [!WARNING]
138 | > **Thinking Tokens are Billed as Output**: The `thoughts_token_count` is part of the generated output and is billed at the output token rate. High thinking levels will significantly increase your output token usage and cost.
139 | 
140 | ## 5. Summary of Key Differences
141 | 
142 | | Feature | Gemini 1.5 Pro | Gemini 3 Pro |
143 | | :--- | :--- | :--- |
144 | | **Reasoning** | Standard | **Advanced (Thinking Process)** |
145 | | **Thinking Control** | N/A | `thinking_level="LOW" | "HIGH"` |
146 | | **Token Metadata** | Standard | Includes `thoughts_token_count` |
147 | | **SDK Requirement** | Older versions OK | Requires `google-genai >= 1.51.0` |
148 | 


--------------------------------------------------------------------------------
/insights.py:
--------------------------------------------------------------------------------
  1 | """Lightweight sidebar summarizer for streaming agent thoughts.
  2 | 
  3 | This helper stays **separate** from the main agents/orchestrator logic.
  4 | It only consumes the recent public transcript (last ~5 steps) and asks a
  5 | cheaper Gemini model (no thinking mode) to condense it into a tiny finding
  6 | plus an optional chart spec the frontend can render.
  7 | """
  8 | 
  9 | from __future__ import annotations
 10 | 
 11 | import json
 12 | import os
 13 | import logging
 14 | from typing import Any, Dict, List, Optional
 15 | 
 16 | from google import genai
 17 | from google.genai import types
 18 | 
 19 | logger = logging.getLogger(__name__)
 20 | 
 21 | 
 22 | _client: Optional[genai.Client] = None
 23 | 
 24 | 
 25 | def _get_client() -> genai.Client:
 26 |     """Lazily create a single Gemini client (re-used across requests)."""
 27 | 
 28 |     global _client
 29 |     if _client is None:
 30 |         api_key = os.environ.get("GOOGLE_API_KEY")
 31 |         if not api_key:
 32 |             raise RuntimeError("GOOGLE_API_KEY is not set")
 33 |         _client = genai.Client(api_key=api_key)
 34 |     return _client
 35 | 
 36 | 
 37 | def _build_prompt(history: List[Dict[str, str]]) -> str:
 38 |     """Format the last few steps into a compact textual context."""
 39 | 
 40 |     lines: List[str] = []
 41 |     for item in history[-5:]:  # hard cap: last 5 turns only
 42 |         role = (item.get("type") or "text").upper()
 43 |         content = (item.get("content") or "").strip()
 44 |         # Trim individual snippets to keep context small and cheap
 45 |         if len(content) > 1600:
 46 |             content = content[:1600] + "\n...[truncated]"
 47 |         lines.append(f"[{role}]\n{content}")
 48 | 
 49 |     return "\n\n".join(lines)
 50 | 
 51 | 
 52 | def summarize_agent_findings(
 53 |     agent_id: str,
 54 |     history: List[Dict[str, str]],
 55 | ) -> Dict[str, Any]:
 56 |     """Return a JSON-friendly finding + optional chart for a single agent.
 57 | 
 58 |     Args:
 59 |         agent_id: Identifier of the sub-agent (for logging only).
 60 |         history: List of dicts with at least ``type`` and ``content`` keys.
 61 |                  Only the 5 most recent entries are used.
 62 | 
 63 |     Returns:
 64 |         {"summary": str, "chart": Optional[dict]}
 65 |     """
 66 |     prompt = _build_prompt(history)
 67 | 
 68 |     if not prompt.strip():
 69 |         return {"summary": "Waiting for agent output...", "chart": None}
 70 | 
 71 |     system_instruction = (
 72 |         "You distill an autonomous research agent's most recent scratch notes "
 73 |         "into crisp sidebar findings. Keep it short (<=120 words), prefer "
 74 |         "bullets, surface concrete numbers, and call out the next action.\n"
 75 |         "If you can see numeric progressions (loss/accuracy/score vs step), "
 76 |         "add a compact chart spec. Use simple types only: line or bar.\n"
 77 |         "Respond as JSON with keys: summary (markdown-safe string) and optional "
 78 |         "chart. Chart shape: {\"title\": str, \"type\": \"line\"|\"bar\", "
 79 |         "\"labels\": [str], \"series\":[{\"name\": str, \"values\": [number]}]}. "
 80 |         "Omit chart if no numeric series are present."
 81 |     )
 82 | 
 83 |     client = _get_client()
 84 | 
 85 |     try:
 86 |         response = client.models.generate_content(
 87 |             model="gemini-3-pro-preview",  # cheaper, no thinking mode
 88 |             contents=[
 89 |                 types.Content(
 90 |                     role="user",
 91 |                     parts=[types.Part.from_text(text=prompt)],
 92 |                 )
 93 |             ],
 94 |             config=types.GenerateContentConfig(
 95 |                 system_instruction=system_instruction,
 96 |                 temperature=0.2,
 97 |                 max_output_tokens=4000,
 98 |             ),
 99 |         )
100 |     except Exception as e:
101 |         logger.error("Gemini summarize failed for agent %s: %s", agent_id, e)
102 |         raise
103 | 
104 |     raw_text = ""
105 |     try:
106 |         # Prefer the convenience accessor if available
107 |         raw_text = getattr(response, "text", "") or ""
108 |         if not raw_text:
109 |             candidate = response.candidates[0]
110 |             if candidate.content and candidate.content.parts:
111 |                 for part in candidate.content.parts:
112 |                     if getattr(part, "text", None):
113 |                         raw_text += part.text
114 |                     elif getattr(part, "inline_data", None) and getattr(part.inline_data, "data", None):
115 |                         try:
116 |                             raw_text += part.inline_data.data.decode("utf-8", errors="ignore")
117 |                         except Exception:
118 |                             pass
119 |         raw_text = raw_text.strip()
120 |     except Exception as e:
121 |         logger.warning("Failed to extract text for agent %s: %s", agent_id, e)
122 | 
123 |     result: Dict[str, Any]
124 |     try:
125 |         result = json.loads(raw_text)
126 |     except Exception as json_err:
127 |         logger.debug(
128 |             "summarize_agent: json decode failed for agent=%s err=%s raw_sample=%s",
129 |             agent_id,
130 |             json_err,
131 |             (raw_text[:200] + ("..." if len(raw_text) > 200 else "")),
132 |         )
133 |         # Heuristic: try to salvage a JSON-ish blob between the first { and last }
134 |         salvaged = None
135 |         if "{" in raw_text and "}" in raw_text:
136 |             candidate_blob = raw_text[raw_text.find("{") : raw_text.rfind("}") + 1]
137 |             try:
138 |                 salvaged = json.loads(candidate_blob)
139 |             except Exception:
140 |                 pass
141 | 
142 |         if salvaged and isinstance(salvaged, dict):
143 |             result = salvaged
144 |         else:
145 |             # Fallback: treat the raw text as the summary string.
146 |             result = {"summary": raw_text or "No summary produced", "chart": None}
147 | 
148 |     # Ensure required fields exist and are JSON-serializable
149 |     if "summary" not in result or not isinstance(result.get("summary"), str):
150 |         result["summary"] = raw_text or "No summary produced"
151 |     if "chart" in result and result["chart"] is not None:
152 |         if not isinstance(result["chart"], dict):
153 |             result["chart"] = None
154 | 
155 |     # Trim overly verbose summaries so the rail stays tight
156 |     if result.get("summary") and len(result["summary"]) > 800:
157 |         result["summary"] = result["summary"][:800] + "..."
158 | 
159 |     return result
160 | 


--------------------------------------------------------------------------------
/frontend/src/lib/api.ts:
--------------------------------------------------------------------------------
  1 | // In production (Railway), the API is served from the same origin
  2 | // In development, we use localhost:8000
  3 | export const API_BASE_URL = import.meta.env.DEV ? "http://localhost:8000" : "";
  4 | 
  5 | // LocalStorage key for user credentials
  6 | const CREDENTIALS_STORAGE_KEY = "ai_researcher_credentials";
  7 | 
  8 | export interface UserCredentials {
  9 |     google_api_key?: string;
 10 |     anthropic_api_key?: string;
 11 |     modal_token_id?: string;
 12 |     modal_token_secret?: string;
 13 | }
 14 | 
 15 | export interface SingleExperimentRequest {
 16 |     task: string;
 17 |     gpu?: string;
 18 |     model?: string;
 19 |     test_mode?: boolean;
 20 |     credentials?: UserCredentials;
 21 | }
 22 | 
 23 | export interface OrchestratorExperimentRequest {
 24 |     task: string;
 25 |     gpu?: string;
 26 |     model?: string;
 27 |     num_agents: number;
 28 |     max_rounds: number;
 29 |     max_parallel: number;
 30 |     test_mode?: boolean;
 31 |     credentials?: UserCredentials;
 32 | }
 33 | 
 34 | export type ExperimentRequest =
 35 |     | SingleExperimentRequest
 36 |     | OrchestratorExperimentRequest;
 37 | 
 38 | export interface LogEvent {
 39 |     type: "line" | "summary";
 40 |     stream?: "stdout" | "stderr";
 41 |     timestamp: string;
 42 |     raw?: string;
 43 |     plain?: string;
 44 |     exit_code?: number;
 45 |     duration_seconds?: number;
 46 | }
 47 | 
 48 | export interface ChartSeries {
 49 |     name: string;
 50 |     values: number[];
 51 | }
 52 | 
 53 | export interface ChartSpec {
 54 |     title?: string;
 55 |     type: "line" | "bar";
 56 |     labels: string[];
 57 |     series: ChartSeries[];
 58 | }
 59 | 
 60 | export interface AgentSummaryRequest {
 61 |     agent_id: string;
 62 |     history: { type: "thought" | "code" | "result" | "text"; content: string }[];
 63 | }
 64 | 
 65 | export interface AgentSummaryResponse {
 66 |     summary: string;
 67 |     chart?: ChartSpec | null;
 68 | }
 69 | 
 70 | export interface CredentialStatus {
 71 |     hasGoogleApiKey: boolean;
 72 |     hasAnthropicApiKey: boolean;
 73 |     hasModalToken: boolean;
 74 | }
 75 | 
 76 | export interface CredentialUpdatePayload {
 77 |     googleApiKey?: string;
 78 |     anthropicApiKey?: string;
 79 |     modalTokenId?: string;
 80 |     modalTokenSecret?: string;
 81 | }
 82 | 
 83 | // ---------------------------------------------------------------------------
 84 | // Local credential storage (browser localStorage)
 85 | // ---------------------------------------------------------------------------
 86 | 
 87 | export function getStoredCredentials(): UserCredentials {
 88 |     try {
 89 |         const stored = localStorage.getItem(CREDENTIALS_STORAGE_KEY);
 90 |         if (stored) {
 91 |             return JSON.parse(stored);
 92 |         }
 93 |     } catch (e) {
 94 |         console.warn("Failed to read stored credentials:", e);
 95 |     }
 96 |     return {};
 97 | }
 98 | 
 99 | export function storeCredentials(creds: CredentialUpdatePayload): void {
100 |     const toStore: UserCredentials = {
101 |         google_api_key: creds.googleApiKey,
102 |         anthropic_api_key: creds.anthropicApiKey,
103 |         modal_token_id: creds.modalTokenId,
104 |         modal_token_secret: creds.modalTokenSecret,
105 |     };
106 |     // Only store non-empty values
107 |     const filtered = Object.fromEntries(
108 |         Object.entries(toStore).filter(([, v]) => v && v.trim())
109 |     );
110 |     localStorage.setItem(CREDENTIALS_STORAGE_KEY, JSON.stringify(filtered));
111 | }
112 | 
113 | export function getLocalCredentialStatus(): CredentialStatus {
114 |     const creds = getStoredCredentials();
115 |     return {
116 |         hasGoogleApiKey: Boolean(creds.google_api_key?.trim()),
117 |         hasAnthropicApiKey: Boolean(creds.anthropic_api_key?.trim()),
118 |         hasModalToken: Boolean(creds.modal_token_id?.trim() && creds.modal_token_secret?.trim()),
119 |     };
120 | }
121 | 
122 | // ---------------------------------------------------------------------------
123 | // API functions
124 | // ---------------------------------------------------------------------------
125 | 
126 | export async function streamExperiment(
127 |     endpoint: "/api/experiments/single/stream" | "/api/experiments/orchestrator/stream",
128 |     payload: ExperimentRequest,
129 |     onData: (data: LogEvent) => void,
130 |     onError: (error: Error) => void,
131 |     onComplete: () => void
132 | ) {
133 |     try {
134 |         // Attach stored credentials to the request
135 |         const credentials = getStoredCredentials();
136 |         const payloadWithCreds = { ...payload, credentials };
137 | 
138 |         const response = await fetch(`${API_BASE_URL}${endpoint}`, {
139 |             method: "POST",
140 |             headers: {
141 |                 "Content-Type": "application/json",
142 |             },
143 |             body: JSON.stringify(payloadWithCreds),
144 |         });
145 | 
146 |         if (!response.ok) {
147 |             throw new Error(`API Error: ${response.status} ${response.statusText}`);
148 |         }
149 | 
150 |         if (!response.body) {
151 |             throw new Error("No response body");
152 |         }
153 | 
154 |         const reader = response.body.getReader();
155 |         const decoder = new TextDecoder();
156 |         let buffer = "";
157 | 
158 |         while (true) {
159 |             const { done, value } = await reader.read();
160 |             if (done) break;
161 | 
162 |             buffer += decoder.decode(value, { stream: true });
163 |             const lines = buffer.split("\n");
164 |             buffer = lines.pop() || "";
165 | 
166 |             for (const line of lines) {
167 |                 if (!line.trim()) continue;
168 |                 try {
169 |                     const event = JSON.parse(line);
170 |                     onData(event);
171 |                 } catch (e) {
172 |                     console.warn("Failed to parse JSON line:", line, e);
173 |                 }
174 |             }
175 |         }
176 | 
177 |         onComplete();
178 |     } catch (error) {
179 |         onError(error instanceof Error ? error : new Error(String(error)));
180 |     }
181 | }
182 | 
183 | export async function summarizeAgent(payload: AgentSummaryRequest): Promise<AgentSummaryResponse> {
184 |     const response = await fetch(`${API_BASE_URL}/api/agents/summarize`, {
185 |         method: "POST",
186 |         headers: { "Content-Type": "application/json" },
187 |         body: JSON.stringify(payload),
188 |     });
189 | 
190 |     if (!response.ok) {
191 |         throw new Error(`Summarizer error: ${response.status} ${response.statusText}`);
192 |     }
193 | 
194 |     const data = (await response.json()) as AgentSummaryResponse;
195 |     return data;
196 | }
197 | 
198 | export async function fetchCredentialStatus(): Promise<CredentialStatus> {
199 |     // In multi-user mode, we check localStorage instead of server
200 |     // Server credentials are only used as fallback
201 |     const localStatus = getLocalCredentialStatus();
202 | 
203 |     // Also check server for fallback (e.g., if server has env vars set)
204 |     try {
205 |         const response = await fetch(`${API_BASE_URL}/api/credentials/status`);
206 |         if (response.ok) {
207 |             const data = await response.json();
208 |             return {
209 |                 hasGoogleApiKey: localStatus.hasGoogleApiKey || Boolean(data.has_google_api_key),
210 |                 hasAnthropicApiKey: localStatus.hasAnthropicApiKey || Boolean(data.has_anthropic_api_key),
211 |                 hasModalToken: localStatus.hasModalToken || Boolean(data.has_modal_token),
212 |             };
213 |         }
214 |     } catch {
215 |         // Server check failed, just use local status
216 |     }
217 | 
218 |     return localStatus;
219 | }
220 | 
221 | export async function saveCredentials(payload: CredentialUpdatePayload): Promise<CredentialStatus> {
222 |     // Store credentials locally in the browser
223 |     storeCredentials(payload);
224 | 
225 |     // Return the new status based on what we just stored + what was already there
226 |     return fetchCredentialStatus();
227 | }
228 | 


--------------------------------------------------------------------------------
/frontend/src/components/Notebook/AgentNotebook.tsx:
--------------------------------------------------------------------------------
  1 | import { useEffect, useRef, useState } from "react";
  2 | import { createPortal } from "react-dom";
  3 | import { Maximize2, Minimize2 } from "lucide-react";
  4 | import { AgentState } from "@/lib/useExperiment";
  5 | import { NotebookCell } from "./NotebookCell";
  6 | import { StatusBadge } from "../StatusBadge";
  7 | import { cn } from "@/lib/utils";
  8 | 
  9 | interface AgentNotebookProps {
 10 |     agent: AgentState;
 11 | }
 12 | 
 13 | function AgentNotebookContent({ 
 14 |     agent, 
 15 |     isExpanded, 
 16 |     onToggleExpand, 
 17 |     isModal = false 
 18 | }: { 
 19 |     agent: AgentState;
 20 |     isExpanded: boolean;
 21 |     onToggleExpand: () => void;
 22 |     isModal?: boolean;
 23 | }) {
 24 |     const scrollRef = useRef<HTMLDivElement>(null);
 25 |     const autoScrollEnabledRef = useRef(true);
 26 |     const isProgrammaticScrollRef = useRef(false);
 27 |     const timeoutRef = useRef<NodeJS.Timeout | null>(null);
 28 | 
 29 |     const scrollToBottom = () => {
 30 |         if (scrollRef.current) {
 31 |             isProgrammaticScrollRef.current = true;
 32 |             scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
 33 |             // Small timeout to ensure the onScroll event fired by this change 
 34 |             // is ignored by our handler.
 35 |             setTimeout(() => {
 36 |                 isProgrammaticScrollRef.current = false;
 37 |             }, 50);
 38 |         }
 39 |     };
 40 | 
 41 |     // Auto-scroll effect
 42 |     useEffect(() => {
 43 |         // We depend on the entire agent object to catch streaming updates
 44 |         if (autoScrollEnabledRef.current) {
 45 |             scrollToBottom();
 46 |         }
 47 |     }, [agent]);
 48 | 
 49 |     const handleScroll = () => {
 50 |         if (!scrollRef.current) return;
 51 | 
 52 |         // Ignore scroll events triggered by our auto-scroll
 53 |         if (isProgrammaticScrollRef.current) {
 54 |             return;
 55 |         }
 56 | 
 57 |         const { scrollTop, scrollHeight, clientHeight } = scrollRef.current;
 58 |         const isAtBottom = scrollHeight - scrollTop - clientHeight < 50;
 59 | 
 60 |         if (isAtBottom) {
 61 |             // User is at the bottom, resume auto-scroll
 62 |             autoScrollEnabledRef.current = true;
 63 |             if (timeoutRef.current) {
 64 |                 clearTimeout(timeoutRef.current);
 65 |                 timeoutRef.current = null;
 66 |             }
 67 |         } else {
 68 |             // User scrolled away
 69 |             autoScrollEnabledRef.current = false;
 70 |             
 71 |             // Set/Reset 10s timeout to resume auto-scroll
 72 |             if (timeoutRef.current) {
 73 |                 clearTimeout(timeoutRef.current);
 74 |             }
 75 |             
 76 |             timeoutRef.current = setTimeout(() => {
 77 |                 autoScrollEnabledRef.current = true;
 78 |                 // Optional: snap back to bottom immediately when timer fires?
 79 |                 // The requirement says "goes back to auto-scroll-to-bottom", 
 80 |                 // which we interpret as re-enabling the behavior. 
 81 |                 // We'll also snap to bottom to make it clear the mode is back.
 82 |                 scrollToBottom();
 83 |             }, 10000);
 84 |         }
 85 |     };
 86 | 
 87 |     return (
 88 |         <div className={cn(
 89 |             "flex flex-col h-full border border-[#1d1d1f] bg-black/50 backdrop-blur-sm transition-all duration-500",
 90 |             isModal ? "border-0 bg-black/95" : ""
 91 |         )}>
 92 |             {/* Header - Ultra Minimal */}
 93 |             <div className="flex-shrink-0 h-12 px-4 border-b border-[#1d1d1f] flex items-center justify-between bg-black/50">
 94 |                 <div className="flex items-center gap-3">
 95 |                     <span className="text-[10px] font-medium text-[#f5f5f7] tracking-widest uppercase">
 96 |                         Agent {agent.id}
 97 |                     </span>
 98 |                     <div className="w-[1px] h-3 bg-[#1d1d1f]" />
 99 |                     <span className="text-[10px] font-medium text-[#6e6e73] uppercase tracking-widest">
100 |                         {agent.gpu || "CPU"}
101 |                     </span>
102 |                 </div>
103 |                 <div className="flex items-center gap-3">
104 |                     <StatusBadge status={agent.status} />
105 |                     <button 
106 |                         onClick={onToggleExpand}
107 |                         className="p-1.5 hover:bg-[#1d1d1f] rounded-md transition-colors text-[#86868b] hover:text-white"
108 |                     >
109 |                         {isExpanded ? <Minimize2 className="w-3.5 h-3.5" /> : <Maximize2 className="w-3.5 h-3.5" />}
110 |                     </button>
111 |                 </div>
112 |             </div>
113 | 
114 |             {/* Hypothesis - Clean & Typography focused */}
115 |             {agent.hypothesis && (
116 |                 <div className="flex-shrink-0 p-4 border-b border-[#1d1d1f] bg-black">
117 |                     <div className="text-[10px] font-medium text-[#424245] uppercase tracking-widest mb-2">
118 |                         Objective
119 |                     </div>
120 |                     <div className={cn(
121 |                         "text-xs text-[#86868b] font-light leading-relaxed",
122 |                         !isExpanded && "line-clamp-2"
123 |                     )}>
124 |                         {agent.hypothesis}
125 |                     </div>
126 |                 </div>
127 |             )}
128 | 
129 |             {/* Notebook Content */}
130 |             <div 
131 |                 ref={scrollRef}
132 |                 onScroll={handleScroll}
133 |                 className={cn(
134 |                     "flex-1 overflow-y-auto p-4 custom-scrollbar scroll-smooth",
135 |                     isModal && "px-8 md:px-16" // Extra padding in modal mode
136 |                 )}
137 |             >
138 |                 <div className={cn(
139 |                     "space-y-8",
140 |                     isModal && "max-w-4xl mx-auto" // Centered content in modal
141 |                 )}>
142 |                     {agent.steps.length === 0 ? (
143 |                         <div className="h-full flex flex-col items-center justify-center min-h-[200px]">
144 |                             <div className="w-1 h-1 rounded-full bg-[#333] mb-3" />
145 |                             <span className="text-[10px] font-medium text-[#424245] uppercase tracking-widest">Initializing Environment</span>
146 |                         </div>
147 |                     ) : (
148 |                         agent.steps.map((step) => (
149 |                             <NotebookCell key={step.id} step={step} />
150 |                         ))
151 |                     )}
152 |                 </div>
153 |             </div>
154 |         </div>
155 |     );
156 | }
157 | 
158 | export function AgentNotebook({ agent }: AgentNotebookProps) {
159 |     const [isExpanded, setIsExpanded] = useState(false);
160 | 
161 |     // Effect to handle body scroll locking when expanded
162 |     useEffect(() => {
163 |         if (isExpanded) {
164 |             document.body.style.overflow = "hidden";
165 |         } else {
166 |             document.body.style.overflow = "unset";
167 |         }
168 |         return () => {
169 |             document.body.style.overflow = "unset";
170 |         };
171 |     }, [isExpanded]);
172 | 
173 |     return (
174 |         <>
175 |             {/* Default View */}
176 |             <div className={cn("h-full", isExpanded && "invisible")}>
177 |                 <AgentNotebookContent 
178 |                     agent={agent} 
179 |                     isExpanded={isExpanded} 
180 |                     onToggleExpand={() => setIsExpanded(!isExpanded)} 
181 |                 />
182 |             </div>
183 | 
184 |             {/* Expanded Modal View */}
185 |             {isExpanded && createPortal(
186 |                 <div className="fixed inset-0 z-[100] bg-black/80 backdrop-blur-md animate-in fade-in duration-200 p-4 md:p-8">
187 |                     <div className="w-full h-full rounded-lg overflow-hidden animate-in zoom-in-95 duration-300 border border-[#1d1d1f] shadow-2xl">
188 |                         <AgentNotebookContent 
189 |                             agent={agent} 
190 |                             isExpanded={isExpanded} 
191 |                             onToggleExpand={() => setIsExpanded(!isExpanded)}
192 |                             isModal={true} 
193 |                         />
194 |                     </div>
195 |                 </div>,
196 |                 document.body
197 |             )}
198 |         </>
199 |     );
200 | }
201 | 


--------------------------------------------------------------------------------
/frontend/src/components/FindingsRail.tsx:
--------------------------------------------------------------------------------
  1 | import { AgentState, AgentInsight } from "@/lib/useExperiment";
  2 | import { ChartSpec } from "@/lib/api";
  3 | import { formatDistanceToNow } from "date-fns";
  4 | import { cn } from "@/lib/utils";
  5 | import ReactMarkdown from "react-markdown";
  6 | import remarkGfm from "remark-gfm";
  7 | import { motion, AnimatePresence } from "framer-motion";
  8 | 
  9 | type InsightWithAgent = AgentInsight & { agentId: string; gpu?: string };
 10 | 
 11 | interface FindingsRailProps {
 12 |     agents: Record<string, AgentState>;
 13 | }
 14 | 
 15 | function MiniChart({ chart }: { chart: ChartSpec }) {
 16 |     const width = 260;
 17 |     const height = 140; // slightly taller to fit axis labels
 18 |     const padding = { top: 14, right: 10, bottom: 28, left: 46 };
 19 | 
 20 |     const series = chart.series?.[0];
 21 |     if (!series || !Array.isArray(series.values) || series.values.length === 0) return null;
 22 | 
 23 |     const values = series.values.map((v) => Number(v)).filter((v) => Number.isFinite(v));
 24 |     if (values.length === 0) return null;
 25 | 
 26 |     const min = Math.min(...values);
 27 |     const max = Math.max(...values);
 28 |     const span = max - min || 1;
 29 | 
 30 |     const innerWidth = width - padding.left - padding.right;
 31 |     const innerHeight = height - padding.top - padding.bottom;
 32 | 
 33 |     const formatNumber = (val: number) => {
 34 |         const abs = Math.abs(val);
 35 |         if (abs >= 1_000_000_000) return `${(val / 1_000_000_000).toFixed(1)}b`;
 36 |         if (abs >= 1_000_000) return `${(val / 1_000_000).toFixed(1)}m`;
 37 |         if (abs >= 1_000) return `${(val / 1_000).toFixed(1)}k`;
 38 |         if (abs >= 100) return val.toFixed(0);
 39 |         if (abs >= 1) return val.toFixed(2);
 40 |         return val.toPrecision(2);
 41 |     };
 42 | 
 43 |     const pts = values.map((v, idx) => {
 44 |         const x = padding.left + (idx / Math.max(values.length - 1, 1)) * innerWidth;
 45 |         const y = padding.top + (1 - (v - min) / span) * innerHeight;
 46 |         return `${x},${y}`;
 47 |     });
 48 | 
 49 |     // Respect labels if they match the series length; otherwise fall back to indices.
 50 |     const xLabels =
 51 |         Array.isArray(chart.labels) && chart.labels.length === values.length
 52 |             ? chart.labels
 53 |             : values.map((_, idx) => `${idx + 1}`);
 54 | 
 55 |     const xTicks = (() => {
 56 |         const maxTicks = 4; // keep tiny chart readable
 57 |         const step = Math.max(1, Math.ceil(xLabels.length / maxTicks));
 58 |         const ticks: { idx: number; label: string; x: number }[] = [];
 59 |         for (let i = 0; i < xLabels.length; i += step) {
 60 |             const x = padding.left + (i / Math.max(xLabels.length - 1, 1)) * innerWidth;
 61 |             ticks.push({ idx: i, label: xLabels[i], x });
 62 |         }
 63 |         // Always include the last label for clarity
 64 |         if (ticks[ticks.length - 1]?.idx !== xLabels.length - 1) {
 65 |             const i = xLabels.length - 1;
 66 |             const x = padding.left + (i / Math.max(xLabels.length - 1, 1)) * innerWidth;
 67 |             ticks.push({ idx: i, label: xLabels[i], x });
 68 |         }
 69 |         return ticks;
 70 |     })();
 71 | 
 72 |     const yTicks = [0, 0.5, 1].map((t) => ({
 73 |         value: min + span * t,
 74 |         y: padding.top + (1 - t) * innerHeight,
 75 |     }));
 76 | 
 77 |     const bars = chart.type === "bar";
 78 | 
 79 |     return (
 80 |         <div className="pt-3">
 81 |             <div className="text-[10px] uppercase tracking-[0.2em] text-[#5c5c63] mb-2 flex items-center justify-between">
 82 |                 <span>{chart.title || "Signal"}</span>
 83 |                 <span className="text-[9px] text-[#7c7c83]">{series.name || "metric"}</span>
 84 |             </div>
 85 |             <svg viewBox={`0 0 ${width} ${height}`} className="w-full h-[140px] text-white/80">
 86 |                 <defs>
 87 |                     <linearGradient id="spark" x1="0" x2="0" y1="0" y2="1">
 88 |                         <stop offset="0%" stopColor="rgba(255,255,255,0.08)" />
 89 |                         <stop offset="100%" stopColor="rgba(255,255,255,0.02)" />
 90 |                     </linearGradient>
 91 |                 </defs>
 92 |                 <rect x="0" y="0" width={width} height={height} fill="url(#spark)" rx="10" />
 93 | 
 94 |                 {/* Grid + axes */}
 95 |                 <g stroke="rgba(255,255,255,0.15)" strokeWidth="1">
 96 |                     {yTicks.map(({ y }, i) => (
 97 |                         <line key={`grid-${i}`} x1={padding.left} x2={width - padding.right} y1={y} y2={y} />
 98 |                     ))}
 99 |                     <line x1={padding.left} x2={padding.left} y1={padding.top} y2={height - padding.bottom} />
100 |                     <line x1={padding.left} x2={width - padding.right} y1={height - padding.bottom} y2={height - padding.bottom} />
101 |                 </g>
102 | 
103 |                 {/* Y-axis labels */}
104 |                 <g fill="rgba(255,255,255,0.65)" fontSize="9" textAnchor="end">
105 |                     {yTicks.map(({ y, value }, i) => (
106 |                         <text key={`ylabel-${i}`} x={padding.left - 6} y={y + 3}>
107 |                             {formatNumber(value)}
108 |                         </text>
109 |                     ))}
110 |                 </g>
111 | 
112 |                 {/* X-axis labels */}
113 |                 <g fill="rgba(255,255,255,0.65)" fontSize="9" textAnchor="middle">
114 |                     {xTicks.map(({ x, label }, i) => (
115 |                         <text key={`xlabel-${i}`} x={x} y={height - 8}>
116 |                             {label}
117 |                         </text>
118 |                     ))}
119 |                 </g>
120 | 
121 |                 {bars ? (
122 |                     values.map((v, idx) => {
123 |                         const barWidth = innerWidth / Math.max(values.length * 1.4, 1);
124 |                         const x = padding.left + idx * (innerWidth / Math.max(values.length - 1, 1));
125 |                         const y = padding.top + (1 - (v - min) / span) * innerHeight;
126 |                         const h = height - padding.bottom - y;
127 |                         return (
128 |                             <rect
129 |                                 key={idx}
130 |                                 x={x - barWidth / 2}
131 |                                 y={y}
132 |                                 width={barWidth}
133 |                                 height={h}
134 |                                 rx={2}
135 |                                 fill="rgba(255,255,255,0.45)"
136 |                             />
137 |                         );
138 |                     })
139 |                 ) : (
140 |                     <polyline
141 |                         fill="none"
142 |                         stroke="white"
143 |                         strokeWidth="2"
144 |                         points={pts.join(" ")}
145 |                         strokeLinejoin="round"
146 |                         strokeLinecap="round"
147 |                     />
148 |                 )}
149 |             </svg>
150 |         </div>
151 |     );
152 | }
153 | 
154 | export function FindingsRail({ agents }: FindingsRailProps) {
155 |     const insights: InsightWithAgent[] = Object.values(agents)
156 |         .flatMap((agent) => (agent.insights || []).map((insight) => ({ ...insight, agentId: agent.id, gpu: agent.gpu })))
157 |         .sort((a, b) => b.timestamp - a.timestamp)
158 |         .slice(0, 24); // Cap to avoid ever-growing rail
159 | 
160 |     return (
161 |         <AnimatePresence>
162 |             {insights.length > 0 && (
163 |                 <motion.aside
164 |                     initial={{ opacity: 0, x: 24 }}
165 |                     animate={{ opacity: 1, x: 0 }}
166 |                     exit={{ opacity: 0, x: 24 }}
167 |                     transition={{ duration: 0.35, ease: "easeOut" }}
168 |                     className="hidden xl:flex w-[340px] shrink-0 h-screen bg-gradient-to-b from-[#0c0c0e] via-[#0a0a0a] to-[#060607] border-l border-white/5 relative overflow-hidden"
169 |                 >
170 |                     <div className="absolute inset-0 opacity-40 pointer-events-none" style={{ background: "radial-gradient(circle at 80% 15%, #1f1f28 0, transparent 45%)" }} />
171 |                     <div className="flex-1 overflow-y-auto custom-scrollbar pt-10 pb-14 px-6 space-y-5">
172 |                         <div className="px-1 space-y-1">
173 |                             <p className="text-[11px] font-semibold tracking-[0.25em] text-white/80 uppercase">Findings</p>
174 |                             <p className="text-[12px] text-[#7c7c83] leading-relaxed">Live distillations of sub-agents—posted whenever they think.</p>
175 |                         </div>
176 | 
177 |                         <div className="space-y-4">
178 |                             {insights.map((insight) => (
179 |                                 <div
180 |                                     key={insight.id}
181 |                                     className={cn(
182 |                                         "p-5 rounded-2xl border border-white/8 bg-white/5 backdrop-blur-xl shadow-[0_20px_60px_rgba(0,0,0,0.35)]",
183 |                                         "hover:border-white/25 transition-all duration-300 hover:-translate-y-0.5"
184 |                                     )}
185 |                                 >
186 |                                     <div className="flex items-center justify-between text-[10px] uppercase tracking-[0.2em] text-[#8a8a92]">
187 |                                         <span className="text-white/90">Agent {insight.agentId}</span>
188 |                                         <span className="text-[#6d6d74]">
189 |                                             {formatDistanceToNow(new Date(insight.timestamp), { addSuffix: true })}
190 |                                         </span>
191 |                                     </div>
192 |                                     <div className="mt-3 text-[11px] text-[#cfd0d4] leading-relaxed prose prose-invert prose-p:my-1 prose-li:my-0 prose-p:text-[#cfd0d4] prose-li:text-[#cfd0d4] prose-strong:text-white prose-code:text-white/80 max-w-none">
193 |                                         <ReactMarkdown remarkPlugins={[remarkGfm]}>
194 |                                             {insight.summary}
195 |                                         </ReactMarkdown>
196 |                                     </div>
197 |                                     {insight.chart && insight.chart.series?.length ? (
198 |                                         <div className="mt-4">
199 |                                             <MiniChart chart={insight.chart} />
200 |                                         </div>
201 |                                     ) : null}
202 |                                 </div>
203 |                             ))}
204 |                         </div>
205 |                     </div>
206 |                 </motion.aside>
207 |             )}
208 |         </AnimatePresence>
209 |     );
210 | }
211 | 


--------------------------------------------------------------------------------
/frontend/src/components/CredentialPrompt.tsx:
--------------------------------------------------------------------------------
  1 | import { CredentialStatus } from "@/lib/api";
  2 | import { AnimatePresence, motion } from "framer-motion";
  3 | import { ExternalLink, KeyRound, Loader2, ShieldCheck, Sparkles, X } from "lucide-react";
  4 | 
  5 | export type CredentialFormState = {
  6 |     googleApiKey: string;
  7 |     anthropicApiKey: string;
  8 |     modalTokenId: string;
  9 |     modalTokenSecret: string;
 10 | };
 11 | 
 12 | type CredentialPromptProps = {
 13 |     open: boolean;
 14 |     status: CredentialStatus | null;
 15 |     selectedModel: "gemini-3-pro-preview" | "claude-opus-4-5";
 16 |     form: CredentialFormState;
 17 |     onChange: (field: keyof CredentialFormState, value: string) => void;
 18 |     onSubmit: () => void;
 19 |     onClose: () => void;
 20 |     isSaving: boolean;
 21 |     error?: string | null;
 22 | };
 23 | 
 24 | export function CredentialPrompt({
 25 |     open,
 26 |     status,
 27 |     selectedModel,
 28 |     form,
 29 |     onChange,
 30 |     onSubmit,
 31 |     onClose,
 32 |     isSaving,
 33 |     error,
 34 | }: CredentialPromptProps) {
 35 |     const googleReady = !!status?.hasGoogleApiKey;
 36 |     const anthropicReady = !!status?.hasAnthropicApiKey;
 37 |     const modalReady = !!status?.hasModalToken;
 38 | 
 39 |     // Determine which key is needed based on selected model
 40 |     const needsGoogleKey = selectedModel === "gemini-3-pro-preview";
 41 |     const needsAnthropicKey = selectedModel === "claude-opus-4-5";
 42 | 
 43 |     const requiredKeyName = needsGoogleKey ? "Google API key" : "Anthropic API key";
 44 |     const hasRequiredKey = needsGoogleKey ? googleReady : anthropicReady;
 45 | 
 46 |     const readinessCopy =
 47 |         hasRequiredKey && modalReady
 48 |             ? "All set — keys already saved locally."
 49 |             : `Needed: ${[
 50 |                   !hasRequiredKey ? requiredKeyName : null,
 51 |                   modalReady ? null : "Modal token (id + secret)",
 52 |               ]
 53 |                   .filter(Boolean)
 54 |                   .join(" + ")}`;
 55 | 
 56 |     const googleProvided = !!form.googleApiKey.trim();
 57 |     const anthropicProvided = !!form.anthropicApiKey.trim();
 58 |     const modalProvided = !!form.modalTokenId.trim() && !!form.modalTokenSecret.trim();
 59 | 
 60 |     // Check if the required key for the selected model is available or provided
 61 |     const hasRequiredLLMKey = needsGoogleKey
 62 |         ? (googleReady || googleProvided)
 63 |         : (anthropicReady || anthropicProvided);
 64 |     const hasModalCredentials = modalReady || modalProvided;
 65 | 
 66 |     const disableSubmit =
 67 |         isSaving || !hasRequiredLLMKey || !hasModalCredentials;
 68 | 
 69 |     return (
 70 |         <AnimatePresence>
 71 |             {open && (
 72 |                 <motion.div
 73 |                     className="fixed inset-0 z-[120] flex items-center justify-center bg-black/70 backdrop-blur-sm px-4"
 74 |                     initial={{ opacity: 0 }}
 75 |                     animate={{ opacity: 1 }}
 76 |                     exit={{ opacity: 0 }}
 77 |                 >
 78 |                     <div className="absolute inset-0 pointer-events-none bg-[radial-gradient(ellipse_at_top,_rgba(255,255,255,0.08),_transparent_45%)]" />
 79 |                     <motion.div
 80 |                         initial={{ opacity: 0, y: 30, scale: 0.97 }}
 81 |                         animate={{ opacity: 1, y: 0, scale: 1 }}
 82 |                         exit={{ opacity: 0, y: 20 }}
 83 |                         transition={{ duration: 0.2 }}
 84 |                         className="relative w-full max-w-4xl overflow-hidden rounded-2xl border border-white/10 bg-[#0b0b0c]/90 shadow-2xl"
 85 |                     >
 86 |                         <div className="absolute inset-x-0 top-0 h-px bg-gradient-to-r from-transparent via-white/30 to-transparent" />
 87 |                         <div className="absolute -left-40 -top-40 h-80 w-80 rounded-full bg-purple-500/10 blur-3xl" />
 88 |                         <div className="absolute -right-32 top-10 h-64 w-64 rounded-full bg-blue-500/10 blur-3xl" />
 89 | 
 90 |                         <div className="relative p-8 md:p-10 space-y-6">
 91 |                             <div className="flex items-start justify-between gap-4">
 92 |                                 <div className="space-y-2">
 93 |                                     <div className="inline-flex items-center gap-2 rounded-full border border-white/10 bg-white/5 px-3 py-1 text-[10px] font-semibold uppercase tracking-[0.22em] text-white/70">
 94 |                                         <Sparkles className="h-3.5 w-3.5 text-amber-300" />
 95 |                                         Environment check
 96 |                                     </div>
 97 |                                     <h2 className="text-2xl font-semibold text-white tracking-tight">
 98 |                                         Add your API keys to launch the run
 99 |                                     </h2>
100 |                                     <p className="text-sm text-white/60 max-w-2xl">
101 |                                         We need at least one LLM key (Google for Gemini or Anthropic for Claude) and a Modal token pair to spin up research sandboxes. Keys are stored locally in your <code className="px-2 py-1 rounded bg-white/5 text-[11px]">.env</code>.
102 |                                     </p>
103 |                                 </div>
104 |                                 <button
105 |                                     onClick={onClose}
106 |                                     className="text-white/60 hover:text-white transition-colors rounded-full p-2 border border-white/10 hover:border-white/30"
107 |                                     aria-label="Close credential prompt"
108 |                                 >
109 |                                     <X className="h-5 w-5" />
110 |                                 </button>
111 |                             </div>
112 | 
113 |                             <div className="grid gap-6 md:grid-cols-[1.1fr_1.2fr]">
114 |                                 <div className="space-y-4 rounded-xl border border-white/10 bg-white/5 p-5">
115 |                                     <div className="flex items-center gap-3">
116 |                                         <ShieldCheck className={`h-5 w-5 ${hasRequiredKey && modalReady ? "text-emerald-400" : "text-amber-300"}`} />
117 |                                         <div className="flex-1">
118 |                                             <p className="text-sm font-medium text-white">Credentials status</p>
119 |                                             <p className="text-xs text-white/60">
120 |                                                 {hasRequiredKey && modalReady
121 |                                                     ? "Ready to launch."
122 |                                                     : "Add the missing keys to continue."}
123 |                                             </p>
124 |                                         </div>
125 |                                     </div>
126 | 
127 |                                     <div className="flex flex-col gap-3">
128 |                                         <StatusPill
129 |                                             label="Google API key (Gemini)"
130 |                                             ok={googleReady}
131 |                                             required={needsGoogleKey}
132 |                                         />
133 |                                         <StatusPill
134 |                                             label="Anthropic API key (Claude)"
135 |                                             ok={anthropicReady}
136 |                                             required={needsAnthropicKey}
137 |                                         />
138 |                                         <StatusPill label="Modal token (compute sandbox)" ok={modalReady} required={true} />
139 |                                     </div>
140 | 
141 |                                     <div className="grid grid-cols-3 gap-3 pt-1">
142 |                                         <a
143 |                                             href="https://aistudio.google.com/app/apikey"
144 |                                             target="_blank"
145 |                                             rel="noreferrer"
146 |                                             className="group inline-flex items-center justify-center gap-2 rounded-lg border border-white/15 bg-gradient-to-r from-white/5 to-white/0 px-3 py-3 text-xs font-medium text-white transition hover:border-white/30 hover:from-white/10"
147 |                                         >
148 |                                             <Sparkles className="h-4 w-4 text-amber-300" />
149 |                                             Google key
150 |                                             <ExternalLink className="h-3 w-3 text-white/50 group-hover:text-white" />
151 |                                         </a>
152 |                                         <a
153 |                                             href="https://console.anthropic.com/settings/keys"
154 |                                             target="_blank"
155 |                                             rel="noreferrer"
156 |                                             className="group inline-flex items-center justify-center gap-2 rounded-lg border border-white/15 bg-gradient-to-r from-white/5 to-white/0 px-3 py-3 text-xs font-medium text-white transition hover:border-white/30 hover:from-white/10"
157 |                                         >
158 |                                             <Sparkles className="h-4 w-4 text-purple-300" />
159 |                                             Anthropic key
160 |                                             <ExternalLink className="h-3 w-3 text-white/50 group-hover:text-white" />
161 |                                         </a>
162 |                                         <a
163 |                                             href="https://modal.com/account/tokens"
164 |                                             target="_blank"
165 |                                             rel="noreferrer"
166 |                                             className="group inline-flex items-center justify-center gap-2 rounded-lg border border-white/15 bg-gradient-to-r from-white/5 to-white/0 px-3 py-3 text-xs font-medium text-white transition hover:border-white/30 hover:from-white/10"
167 |                                         >
168 |                                             <KeyRound className="h-4 w-4 text-sky-300" />
169 |                                             Modal tokens
170 |                                             <ExternalLink className="h-3 w-3 text-white/50 group-hover:text-white" />
171 |                                         </a>
172 |                                     </div>
173 |                                 </div>
174 | 
175 |                                 <div className="space-y-4 rounded-xl border border-white/10 bg-black/60 p-5">
176 |                                     <Field
177 |                                         label="Google API key"
178 |                                         placeholder="Paste your AI Studio key"
179 |                                         value={form.googleApiKey}
180 |                                         onChange={(value) => onChange("googleApiKey", value)}
181 |                                         status={googleReady ? "ok" : needsGoogleKey ? "missing" : "optional"}
182 |                                         helper="Used for Gemini 3 Pro (stored locally)."
183 |                                     />
184 |                                     <Field
185 |                                         label="Anthropic API key"
186 |                                         placeholder="Paste your Anthropic key"
187 |                                         value={form.anthropicApiKey}
188 |                                         onChange={(value) => onChange("anthropicApiKey", value)}
189 |                                         status={anthropicReady ? "ok" : needsAnthropicKey ? "missing" : "optional"}
190 |                                         helper="Used for Claude Opus 4.5 (stored locally)."
191 |                                     />
192 |                                     <Field
193 |                                         label="Modal token ID"
194 |                                         placeholder="modal-token-id"
195 |                                         value={form.modalTokenId}
196 |                                         onChange={(value) => onChange("modalTokenId", value)}
197 |                                         status={modalReady ? "ok" : "missing"}
198 |                                         helper="Pair with the secret to deploy sandboxes."
199 |                                     />
200 |                                     <Field
201 |                                         label="Modal token secret"
202 |                                         placeholder="modal-token-secret"
203 |                                         value={form.modalTokenSecret}
204 |                                         onChange={(value) => onChange("modalTokenSecret", value)}
205 |                                         status={modalReady ? "ok" : "missing"}
206 |                                         helper="Kept locally in your .env file."
207 |                                     />
208 | 
209 |                                     {error && (
210 |                                         <div className="rounded-lg border border-red-500/30 bg-red-500/10 px-3 py-2 text-sm text-red-200">
211 |                                             {error}
212 |                                         </div>
213 |                                     )}
214 | 
215 |                                     <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between pt-1">
216 |                                         <p className="text-xs text-white/50">{readinessCopy}</p>
217 |                                         <button
218 |                                             onClick={onSubmit}
219 |                                             disabled={disableSubmit}
220 |                                             className="inline-flex items-center justify-center gap-2 rounded-lg bg-white px-4 py-2.5 text-sm font-semibold text-black transition hover:bg-white/90 disabled:cursor-not-allowed disabled:bg-white/40"
221 |                                         >
222 |                                             {isSaving ? (
223 |                                                 <>
224 |                                                     <Loader2 className="h-4 w-4 animate-spin" />
225 |                                                     Saving...
226 |                                                 </>
227 |                                             ) : (
228 |                                                 <>
229 |                                                     Save &amp; continue
230 |                                                     <ShieldCheck className="h-4 w-4" />
231 |                                                 </>
232 |                                             )}
233 |                                         </button>
234 |                                     </div>
235 |                                 </div>
236 |                             </div>
237 |                         </div>
238 |                     </motion.div>
239 |                 </motion.div>
240 |             )}
241 |         </AnimatePresence>
242 |     );
243 | }
244 | 
245 | type StatusPillProps = {
246 |     label: string;
247 |     ok: boolean;
248 |     required?: boolean;
249 | };
250 | 
251 | function StatusPill({ label, ok, required = true }: StatusPillProps) {
252 |     // If not required and not ok, show as "optional" (gray/neutral)
253 |     const isOptional = !required && !ok;
254 | 
255 |     return (
256 |         <div className={`flex items-center justify-between rounded-lg border border-white/10 bg-white/5 px-3 py-2 ${isOptional ? "opacity-50" : ""}`}>
257 |             <span className="text-sm text-white/80">{label}</span>
258 |             <span
259 |                 className={`inline-flex items-center gap-2 rounded-full px-3 py-1 text-[11px] font-semibold ${
260 |                     ok
261 |                         ? "bg-emerald-500/15 text-emerald-200"
262 |                         : isOptional
263 |                         ? "bg-white/5 text-white/40"
264 |                         : "bg-amber-500/10 text-amber-200"
265 |                 }`}
266 |             >
267 |                 <div
268 |                     className={`h-2 w-2 rounded-full ${
269 |                         ok
270 |                             ? "bg-emerald-400 shadow-[0_0_0_4px_rgba(52,211,153,0.2)]"
271 |                             : isOptional
272 |                             ? "bg-white/30"
273 |                             : "bg-amber-300 shadow-[0_0_0_4px_rgba(251,191,36,0.25)]"
274 |                     }`}
275 |                 />
276 |                 {ok ? "Ready" : isOptional ? "Optional" : "Missing"}
277 |             </span>
278 |         </div>
279 |     );
280 | }
281 | 
282 | type FieldProps = {
283 |     label: string;
284 |     placeholder: string;
285 |     value: string;
286 |     onChange: (value: string) => void;
287 |     status: "ok" | "missing" | "optional";
288 |     helper?: string;
289 | };
290 | 
291 | function Field({ label, placeholder, value, onChange, status, helper }: FieldProps) {
292 |     const statusText = status === "ok" ? "Optional (already set)" : status === "optional" ? "Optional" : "Required";
293 |     const statusColor = status === "ok" ? "text-emerald-300" : status === "optional" ? "text-blue-300" : "text-amber-200";
294 | 
295 |     return (
296 |         <label className="block space-y-2">
297 |             <div className="flex items-center justify-between">
298 |                 <span className="text-sm font-medium text-white">{label}</span>
299 |                 <span className={`text-[11px] uppercase tracking-[0.18em] ${statusColor}`}>
300 |                     {statusText}
301 |                 </span>
302 |             </div>
303 |             <input
304 |                 value={value}
305 |                 onChange={(e) => onChange(e.target.value)}
306 |                 placeholder={placeholder}
307 |                 className="w-full rounded-lg border border-white/10 bg-white/5 px-3 py-2.5 text-sm text-white placeholder:text-white/30 focus:border-white/50 focus:outline-none"
308 |             />
309 |             {helper && <p className="text-xs text-white/50">{helper}</p>}
310 |         </label>
311 |     );
312 | }
313 | 


--------------------------------------------------------------------------------
/frontend/src/components/Notebook/ResearchPaper.tsx:
--------------------------------------------------------------------------------
  1 | import { useMemo, useState } from "react";
  2 | import { createPortal } from "react-dom";
  3 | import { FileText, X, Download, Printer, BookOpen } from "lucide-react";
  4 | import ReactMarkdown from "react-markdown";
  5 | import remarkGfm from "remark-gfm";
  6 | import { ChartSpec } from "@/lib/api";
  7 | 
  8 | interface ResearchPaperProps {
  9 |     content: string;
 10 |     charts?: ChartSpec[];
 11 | }
 12 | 
 13 | function PaperChart({ chart, compact = false }: { chart: ChartSpec; compact?: boolean }) {
 14 |     const width = compact ? 340 : 640;
 15 |     const height = compact ? 140 : 240;
 16 |     const padding = compact
 17 |         ? { top: 14, right: 10, bottom: 28, left: 46 }
 18 |         : { top: 18, right: 18, bottom: 42, left: 64 };
 19 | 
 20 |     const series = chart.series?.[0];
 21 |     const values = useMemo(
 22 |         () => (series?.values || []).map((v) => Number(v)).filter((v) => Number.isFinite(v)),
 23 |         [series],
 24 |     );
 25 |     if (!series || !values.length) return null;
 26 | 
 27 |     const min = Math.min(...values);
 28 |     const max = Math.max(...values);
 29 |     const span = max - min || 1;
 30 | 
 31 |     const innerWidth = width - padding.left - padding.right;
 32 |     const innerHeight = height - padding.top - padding.bottom;
 33 | 
 34 |     const formatNumber = (val: number) => {
 35 |         const abs = Math.abs(val);
 36 |         if (abs >= 1_000_000_000) return `${(val / 1_000_000_000).toFixed(1)}b`;
 37 |         if (abs >= 1_000_000) return `${(val / 1_000_000).toFixed(1)}m`;
 38 |         if (abs >= 1_000) return `${(val / 1_000).toFixed(1)}k`;
 39 |         if (abs >= 100) return val.toFixed(0);
 40 |         if (abs >= 1) return val.toFixed(2);
 41 |         return val.toPrecision(2);
 42 |     };
 43 | 
 44 |     const xLabels =
 45 |         Array.isArray(chart.labels) && chart.labels.length === values.length
 46 |             ? chart.labels
 47 |             : values.map((_, idx) => `${idx + 1}`);
 48 | 
 49 |     const xTicks = useMemo(() => {
 50 |         const maxTicks = compact ? 4 : 6;
 51 |         const step = Math.max(1, Math.ceil(xLabels.length / maxTicks));
 52 |         const ticks: { idx: number; label: string; x: number }[] = [];
 53 |         for (let i = 0; i < xLabels.length; i += step) {
 54 |             const x = padding.left + (i / Math.max(xLabels.length - 1, 1)) * innerWidth;
 55 |             ticks.push({ idx: i, label: xLabels[i], x });
 56 |         }
 57 |         if (ticks[ticks.length - 1]?.idx !== xLabels.length - 1) {
 58 |             const i = xLabels.length - 1;
 59 |             const x = padding.left + (i / Math.max(xLabels.length - 1, 1)) * innerWidth;
 60 |             ticks.push({ idx: i, label: xLabels[i], x });
 61 |         }
 62 |         return ticks;
 63 |     }, [xLabels, padding.left, innerWidth, compact]);
 64 | 
 65 |     const yTicks = [0, 0.5, 1].map((t) => ({
 66 |         value: min + span * t,
 67 |         y: padding.top + (1 - t) * innerHeight,
 68 |     }));
 69 | 
 70 |     const points = values.map((v, idx) => {
 71 |         const x = padding.left + (idx / Math.max(values.length - 1, 1)) * innerWidth;
 72 |         const y = padding.top + (1 - (v - min) / span) * innerHeight;
 73 |         return `${x},${y}`;
 74 |     });
 75 | 
 76 |     const bars = chart.type === "bar";
 77 | 
 78 |     return (
 79 |         <figure className="bg-white border border-gray-200 rounded-md shadow-sm overflow-hidden">
 80 |             <div className="flex items-center justify-between px-4 py-2 text-[11px] uppercase tracking-[0.16em] text-gray-500 bg-gray-50 border-b border-gray-200">
 81 |                 <span className="font-semibold text-gray-800">{chart.title || "Generated Chart"}</span>
 82 |                 <span className="text-gray-500">
 83 |                     {series.name || "Series"} · {chart.type === "bar" ? "Bar" : "Line"}
 84 |                 </span>
 85 |             </div>
 86 |             <svg viewBox={`0 0 ${width} ${height}`} className="w-full h-auto text-black">
 87 |                 <defs>
 88 |                     <linearGradient id="paper-spark" x1="0" x2="0" y1="0" y2="1">
 89 |                         <stop offset="0%" stopColor="rgba(0,0,0,0.06)" />
 90 |                         <stop offset="100%" stopColor="rgba(0,0,0,0.01)" />
 91 |                     </linearGradient>
 92 |                 </defs>
 93 |                 <rect x="0" y="0" width={width} height={height} fill="url(#paper-spark)" />
 94 | 
 95 |                 {/* Grid + axes */}
 96 |                 <g stroke="rgba(0,0,0,0.1)" strokeWidth="1">
 97 |                     {yTicks.map(({ y }, i) => (
 98 |                         <line key={`grid-${i}`} x1={padding.left} x2={width - padding.right} y1={y} y2={y} />
 99 |                     ))}
100 |                     <line x1={padding.left} x2={padding.left} y1={padding.top} y2={height - padding.bottom} />
101 |                     <line x1={padding.left} x2={width - padding.right} y1={height - padding.bottom} y2={height - padding.bottom} />
102 |                 </g>
103 | 
104 |                 <g fill="rgba(0,0,0,0.6)" fontSize="10" textAnchor="end">
105 |                     {yTicks.map(({ y, value }, i) => (
106 |                         <text key={`ylabel-${i}`} x={padding.left - 8} y={y + 3}>
107 |                             {formatNumber(value)}
108 |                         </text>
109 |                     ))}
110 |                 </g>
111 | 
112 |                 <g fill="rgba(0,0,0,0.6)" fontSize="10" textAnchor="middle">
113 |                     {xTicks.map(({ x, label }, i) => (
114 |                         <text key={`xlabel-${i}`} x={x} y={height - 12}>
115 |                             {label}
116 |                         </text>
117 |                     ))}
118 |                 </g>
119 | 
120 |                 {bars ? (
121 |                     values.map((v, idx) => {
122 |                         const barWidth = innerWidth / Math.max(values.length * 1.15, 1);
123 |                         const x = padding.left + idx * (innerWidth / Math.max(values.length - 1, 1));
124 |                         const y = padding.top + (1 - (v - min) / span) * innerHeight;
125 |                         const h = height - padding.bottom - y;
126 |                         return (
127 |                             <rect
128 |                                 key={idx}
129 |                                 x={x - barWidth / 2}
130 |                                 y={y}
131 |                                 width={barWidth}
132 |                                 height={Math.max(h, 1)}
133 |                                 rx={2}
134 |                                 fill="rgba(34,114,244,0.65)"
135 |                             />
136 |                         );
137 |                     })
138 |                 ) : (
139 |                     <polyline
140 |                         fill="none"
141 |                         stroke="#1f3a93"
142 |                         strokeWidth="2.25"
143 |                         points={points.join(" ")}
144 |                         strokeLinejoin="round"
145 |                         strokeLinecap="round"
146 |                     />
147 |                 )}
148 |             </svg>
149 |             <figcaption className="px-4 py-3 text-xs text-gray-600 border-t border-gray-100">
150 |                 {chart.title || "Figure"} — {series.name || "metric"} over steps. Labels: {xLabels.slice(0, 3).join(", ")}
151 |                 {xLabels.length > 3 ? "…" : ""}.
152 |             </figcaption>
153 |         </figure>
154 |     );
155 | }
156 | 
157 | export function ResearchPaper({ content, charts }: ResearchPaperProps) {
158 |     const [isFullView, setIsFullView] = useState(false);
159 | 
160 |     return (
161 |         <>
162 |             {/* Minimal Inline View */}
163 |             <div className="w-full animate-in fade-in slide-in-from-bottom-8 duration-1000 pt-8">
164 |                 <div className="border border-[#1d1d1f] bg-black/50 backdrop-blur-sm rounded-lg overflow-hidden group hover:border-[#333] transition-colors">
165 |                     {/* Header */}
166 |                     <div className="h-12 px-4 border-b border-[#1d1d1f] flex items-center justify-between bg-black/50">
167 |                         <div className="flex items-center gap-3">
168 |                             <div className="w-1.5 h-1.5 rounded-full bg-green-500 shadow-[0_0_8px_rgba(34,197,94,0.4)]" />
169 |                             <span className="text-[10px] font-medium text-[#f5f5f7] tracking-widest uppercase">
170 |                                 Final Manuscript
171 |                             </span>
172 |                         </div>
173 |                         <button
174 |                             onClick={() => setIsFullView(true)}
175 |                             className="flex items-center gap-2 px-3 py-1.5 rounded-full bg-[#1d1d1f] hover:bg-[#333] transition-all duration-300 group/btn"
176 |                         >
177 |                             <FileText className="w-3 h-3 text-[#86868b] group-hover/btn:text-white transition-colors" />
178 |                             <span className="text-[10px] font-medium text-[#86868b] group-hover/btn:text-white transition-colors uppercase tracking-wide">
179 |                                 View Paper
180 |                             </span>
181 |                         </button>
182 |                     </div>
183 | 
184 |                     {/* Preview Content */}
185 |                     <div className="p-8 max-h-[400px] overflow-hidden relative bg-[#050505]">
186 |                         <div className="prose prose-invert prose-sm max-w-none prose-p:text-[#86868b] prose-headings:text-[#f5f5f7] prose-strong:text-[#f5f5f7] font-serif">
187 |                             <ReactMarkdown remarkPlugins={[remarkGfm]}>
188 |                                 {content}
189 |                             </ReactMarkdown>
190 |                         </div>
191 |                         {charts && charts.length > 0 && (
192 |                             <div className="mt-6 space-y-3">
193 |                                 <p className="text-[10px] tracking-[0.18em] uppercase text-[#6f6f77]">Figures (preview)</p>
194 |                                 <div className="flex gap-3 overflow-x-auto pb-2">
195 |                                     {charts.slice(0, 3).map((chart, idx) => (
196 |                                         <div key={idx} className="min-w-[320px] bg-[#0b0b0b] border border-[#1d1d1f] rounded-lg">
197 |                                             <PaperChart chart={chart} compact />
198 |                                         </div>
199 |                                     ))}
200 |                                 </div>
201 |                             </div>
202 |                         )}
203 |                         {/* Gradient Fade */}
204 |                         <div className="absolute inset-x-0 bottom-0 h-32 bg-gradient-to-t from-[#050505] to-transparent pointer-events-none" />
205 |                     </div>
206 |                 </div>
207 |             </div>
208 | 
209 |             {/* Full View Overlay */}
210 |             {isFullView && createPortal(
211 |                 <div className="fixed inset-0 z-[100] bg-[#e8e8e8]/95 backdrop-blur-md animate-in fade-in duration-200 flex items-center justify-center p-0 sm:p-4 md:p-8 overflow-hidden">
212 |                     <div className="w-full max-w-[1000px] h-full bg-[#fdfdfd] text-black shadow-2xl flex flex-col overflow-hidden animate-in zoom-in-95 duration-300 rounded-sm sm:border border-gray-300">
213 |                         {/* Clean Header Bar */}
214 |                         <div className="h-16 border-b border-gray-200 flex items-center justify-between px-6 bg-white flex-shrink-0 z-10 shadow-sm">
215 |                             <div className="flex items-center gap-6">
216 |                                 <div className="flex items-center gap-3">
217 |                                     <div className="bg-black text-white p-1.5 rounded-md">
218 |                                         <BookOpen className="w-4 h-4" />
219 |                                     </div>
220 |                                     <span className="text-sm font-medium text-gray-900 tracking-tight">Research Preview</span>
221 |                                 </div>
222 |                                 <div className="hidden md:flex items-center gap-4 text-sm text-gray-500">
223 |                                     <span className="px-2 py-0.5 bg-gray-100 rounded-full text-xs font-medium text-gray-600">Final Draft</span>
224 |                                 </div>
225 |                             </div>
226 |                             <div className="flex items-center gap-3">
227 |                                 <button className="hidden md:flex items-center gap-2 px-3 py-1.5 text-gray-600 hover:bg-gray-100 rounded transition-colors">
228 |                                     <Download className="w-4 h-4" />
229 |                                     <span className="text-xs font-medium">PDF</span>
230 |                                 </button>
231 |                                 <button 
232 |                                     onClick={() => window.print()}
233 |                                     className="hidden md:flex items-center gap-2 px-3 py-1.5 text-gray-600 hover:bg-gray-100 rounded transition-colors"
234 |                                 >
235 |                                     <Printer className="w-4 h-4" />
236 |                                     <span className="text-xs font-medium">Print</span>
237 |                                 </button>
238 |                                 <div className="h-4 w-[1px] bg-gray-300 mx-1" />
239 |                                 <button 
240 |                                     onClick={() => setIsFullView(false)}
241 |                                     className="p-2 hover:bg-gray-100 rounded-full transition-colors text-gray-500 hover:text-black"
242 |                                 >
243 |                                     <X className="w-5 h-5" />
244 |                                 </button>
245 |                             </div>
246 |                         </div>
247 | 
248 |                         {/* Paper Content Area - "The Page" */}
249 |                         <div className="flex-1 overflow-y-auto bg-[#e6e6e6] custom-scrollbar-light">
250 |                             <div className="min-h-full w-full flex justify-center p-4 md:p-8">
251 |                                 <div id="printable-paper-content" className="bg-white w-full max-w-[8.5in] min-h-[11in] h-fit shadow-sm p-8 md:p-[1in] selection:bg-blue-100 selection:text-black">
252 |                                     <article className="prose max-w-none font-serif text-black">
253 |                                         {/* Style Overrides for "Paper" look */}
254 |                                         <style>{`
255 |                                             .prose h1 { 
256 |                                                 text-align: center; 
257 |                                                 font-family: "Times New Roman", Times, serif;
258 |                                                 margin-bottom: 0.5em;
259 |                                                 font-size: 2.25rem;
260 |                                                 line-height: 1.1;
261 |                                                 color: #000;
262 |                                                 font-weight: 500;
263 |                                             }
264 |                                             .prose h2 {
265 |                                                 font-family: "Times New Roman", Times, serif;
266 |                                                 font-size: 1.25rem;
267 |                                                 margin-top: 2em;
268 |                                                 color: #000;
269 |                                                 border-bottom: 1px solid #eee;
270 |                                                 padding-bottom: 0.3em;
271 |                                             }
272 |                                             .prose p {
273 |                                                 font-family: "Times New Roman", Times, serif;
274 |                                                 text-align: justify;
275 |                                                 font-size: 1.05rem;
276 |                                                 line-height: 1.6;
277 |                                                 margin-bottom: 1.2em;
278 |                                                 color: #1a1a1a;
279 |                                             }
280 |                                             .prose strong {
281 |                                                 font-weight: 600;
282 |                                                 color: #000;
283 |                                             }
284 |                                             .prose ul {
285 |                                                 list-style-type: disc;
286 |                                                 padding-left: 1.5em;
287 |                                             }
288 |                                             .prose li {
289 |                                                 font-family: "Times New Roman", Times, serif;
290 |                                                 margin-bottom: 0.5em;
291 |                                             }
292 |                                             /* Abstract Styling Attempt */
293 |                                             .prose h2:first-of-type {
294 |                                                 text-align: center;
295 |                                                 font-size: 0.9rem;
296 |                                                 text-transform: uppercase;
297 |                                                 letter-spacing: 0.05em;
298 |                                                 border-bottom: none;
299 |                                                 margin-top: 2em;
300 |                                                 margin-bottom: 1em;
301 |                                             }
302 |                                         `}</style>
303 |                                         
304 |                                         <ReactMarkdown 
305 |                                             remarkPlugins={[remarkGfm]}
306 |                                             components={{
307 |                                                 h1: ({node, ...props}) => <h1 {...props} />,
308 |                                             }}
309 |                                         >
310 |                                             {content}
311 |                                         </ReactMarkdown>
312 | 
313 |                                         {charts && charts.length > 0 && (
314 |                                             <section>
315 |                                                 <h2>Figures</h2>
316 |                                                 <div className="space-y-6">
317 |                                                     {charts.map((chart, idx) => (
318 |                                                         <div key={idx} className="space-y-2">
319 |                                                             <div className="text-sm text-gray-600 font-medium">
320 |                                                                 Figure {idx + 1}. {chart.title || "Generated chart"}
321 |                                                             </div>
322 |                                                             <PaperChart chart={chart} />
323 |                                                         </div>
324 |                                                     ))}
325 |                                                 </div>
326 |                                             </section>
327 |                                         )}
328 |                                         
329 |                                         {/* Footer */}
330 |                                         <div className="mt-24 pt-8 border-t border-gray-200 flex flex-col items-center gap-2 text-gray-400">
331 |                                             <p className="text-[10px] font-mono">Preprint generated by AI Researcher</p>
332 |                                         </div>
333 |                                     </article>
334 |                                 </div>
335 |                             </div>
336 |                         </div>
337 |                     </div>
338 |                 </div>,
339 |                 document.body
340 |             )}
341 |         </>
342 |     );
343 | }
344 | 


--------------------------------------------------------------------------------
/frontend/src/lib/useExperiment.ts:
--------------------------------------------------------------------------------
  1 | import { useState, useRef } from "react";
  2 | import { streamExperiment, LogEvent, summarizeAgent, ChartSpec } from "./api";
  3 | 
  4 | export type StepType = "thought" | "code" | "result" | "text";
  5 | 
  6 | export interface ExperimentStep {
  7 |     id: string;
  8 |     type: StepType;
  9 |     content: string;
 10 |     metadata?: Record<string, any>;
 11 |     timestamp: number;
 12 | }
 13 | 
 14 | export interface AgentInsight {
 15 |     id: string;
 16 |     summary: string;
 17 |     chart?: ChartSpec | null;
 18 |     timestamp: number;
 19 | }
 20 | 
 21 | export interface AgentState {
 22 |     id: string;
 23 |     status: "idle" | "running" | "completed" | "failed";
 24 |     hypothesis?: string;
 25 |     gpu?: string;
 26 |     logs: string[];
 27 |     exitCode?: number;
 28 |     steps: ExperimentStep[];
 29 |     insights: AgentInsight[];
 30 | }
 31 | 
 32 | export type TimelineItem =
 33 |     | { type: "thought"; content: string; timestamp: number }
 34 |     | { type: "agents"; agentIds: string[]; timestamp: number }
 35 |     | { type: "paper"; content: string; charts?: ChartSpec[]; timestamp: number };
 36 | 
 37 | export interface OrchestratorState {
 38 |     status: "idle" | "planning" | "running" | "completed";
 39 |     thoughts: string[];
 40 |     plan: string[];
 41 |     timeline: TimelineItem[];
 42 | }
 43 | 
 44 | export function useExperiment() {
 45 |     const [isRunning, setIsRunning] = useState(false);
 46 |     const [logs, setLogs] = useState<LogEvent[]>([]);
 47 |     const [agents, setAgents] = useState<Record<string, AgentState>>({});
 48 |     const [orchestrator, setOrchestrator] = useState<OrchestratorState>({
 49 |         status: "idle",
 50 |         thoughts: [],
 51 |         plan: [],
 52 |         timeline: [],
 53 |     });
 54 |     const [error, setError] = useState<string | null>(null);
 55 | 
 56 |     // Keep track of the latest agents state to update it functionally
 57 |     const agentsRef = useRef<Record<string, AgentState>>({});
 58 |     const summaryTimersRef = useRef<Record<string, NodeJS.Timeout | null>>({});
 59 |     const summaryInflightRef = useRef<Record<string, boolean>>({});
 60 | 
 61 |     const updateAgent = (id: string, update: Partial<AgentState>) => {
 62 |         setAgents((prev) => {
 63 |             const current = prev[id] || { id, status: "idle", logs: [], steps: [], insights: [] };
 64 |             const next = {
 65 |                 ...prev,
 66 |                 [id]: { ...current, ...update },
 67 |             };
 68 |             agentsRef.current = next;
 69 |             return next;
 70 |         });
 71 |     };
 72 | 
 73 |     const addAgentStep = (id: string, step: Omit<ExperimentStep, "id" | "timestamp">) => {
 74 |         setAgents((prev) => {
 75 |             const current = prev[id] || { id, status: "idle", logs: [], steps: [], insights: [] };
 76 |             const newStep: ExperimentStep = {
 77 |                 ...step,
 78 |                 id: Math.random().toString(36).substring(7),
 79 |                 timestamp: Date.now(),
 80 |             };
 81 | 
 82 |             const next = {
 83 |                 ...prev,
 84 |                 [id]: {
 85 |                     ...current,
 86 |                     steps: [...current.steps, newStep],
 87 |                 },
 88 |             };
 89 |             agentsRef.current = next;
 90 |             return next;
 91 |         });
 92 |     };
 93 | 
 94 |     const appendToLatestAgentStep = (id: string, type: StepType, chunk: string) => {
 95 |         setAgents((prev) => {
 96 |             const current = prev[id];
 97 |             if (!current) return prev;
 98 | 
 99 |             const steps = [...current.steps];
100 | 
101 |             const newStep: ExperimentStep = {
102 |                 id: Math.random().toString(36).substring(7),
103 |                 type,
104 |                 content: chunk,
105 |                 timestamp: Date.now(),
106 |             };
107 | 
108 |             // If there are no steps yet, create the first one so we can stream into it.
109 |             if (steps.length === 0) {
110 |                 const next = {
111 |                     ...prev,
112 |                     [id]: {
113 |                         ...current,
114 |                         steps: [newStep],
115 |                     },
116 |                 };
117 |                 agentsRef.current = next;
118 |                 return next;
119 |             }
120 | 
121 |             const lastStep = steps[steps.length - 1];
122 | 
123 |             // If the last step matches the type, append to it.
124 |             if (lastStep.type === type) {
125 |                 steps[steps.length - 1] = {
126 |                     ...lastStep,
127 |                     content: lastStep.content + chunk,
128 |                 };
129 |             } else {
130 |                 // Fallback: create new step if types mismatch
131 |                 steps.push(newStep);
132 |             }
133 | 
134 |             const next = {
135 |                 ...prev,
136 |                 [id]: { ...current, steps },
137 |             };
138 |             agentsRef.current = next;
139 |             return next;
140 |         });
141 |     };
142 | 
143 |     const addAgentInsight = (id: string, insight: Omit<AgentInsight, "id" | "timestamp"> & { id?: string; timestamp?: number }) => {
144 |         setAgents((prev) => {
145 |             const current = prev[id];
146 |             if (!current) return prev;
147 | 
148 |             const nextInsight: AgentInsight = {
149 |                 id: insight.id || Math.random().toString(36).substring(7),
150 |                 timestamp: insight.timestamp || Date.now(),
151 |                 summary: insight.summary,
152 |                 chart: insight.chart,
153 |             };
154 | 
155 |             const next = {
156 |                 ...prev,
157 |                 [id]: {
158 |                     ...current,
159 |                     insights: [...(current.insights || []), nextInsight],
160 |                 },
161 |             };
162 | 
163 |             agentsRef.current = next;
164 |             return next;
165 |         });
166 |     };
167 | 
168 |     const appendToLatestOrchestratorStep = (type: "thought" | "text", chunk: string) => {
169 |         setOrchestrator((prev) => {
170 |             const timeline = [...prev.timeline];
171 |             const lastItem = timeline[timeline.length - 1];
172 |             
173 |             // Check if we can append to the last item
174 |             if (lastItem && lastItem.type === type) {
175 |                 timeline[timeline.length - 1] = {
176 |                     ...lastItem,
177 |                     content: lastItem.content + chunk
178 |                 };
179 |                 
180 |                 // Also update thoughts array if it's a thought
181 |                 let thoughts = prev.thoughts;
182 |                 if (type === "thought") {
183 |                     thoughts = [...prev.thoughts];
184 |                     if (thoughts.length > 0) {
185 |                         thoughts[thoughts.length - 1] = thoughts[thoughts.length - 1] + chunk;
186 |                     } else {
187 |                         thoughts.push(chunk);
188 |                     }
189 |                 }
190 |                 
191 |                 return { ...prev, timeline, thoughts };
192 |             } else {
193 |                 // Create new item
194 |                 const newItem: TimelineItem = {
195 |                     type: type as any, // 'text' isn't in TimelineItem type explicitly? let's check
196 |                     content: chunk,
197 |                     timestamp: Date.now()
198 |                 };
199 |                 
200 |                 // TimelineItem is: thought | agents | paper. 
201 |                 // If 'text' is meant to be something else, we might need to adjust.
202 |                 // But 'thought' is definitely supported.
203 |                 if (type !== "thought") {
204 |                     // For now orchestrator only really supports 'thought' and 'paper' and 'agents' in timeline
205 |                     // If we have general text messages, maybe treat as thoughts or ignore?
206 |                     // Orchestrator messages are usually shown as 'info' panels in CLI.
207 |                     // In frontend timeline, we map 'thought' to the Orchestrator block.
208 |                     // Let's assume 'thought' for now.
209 |                     return prev;
210 |                 }
211 | 
212 |                 return {
213 |                     ...prev,
214 |                     timeline: [...timeline, newItem],
215 |                     thoughts: [...prev.thoughts, chunk]
216 |                 };
217 |             }
218 |         });
219 |     };
220 | 
221 |     const runAgentSummary = async (agentId: string) => {
222 |         // Clear pending timer marker
223 |         summaryTimersRef.current[agentId] = null;
224 | 
225 |         if (summaryInflightRef.current[agentId]) return;
226 | 
227 |         const agent = agentsRef.current[agentId];
228 |         if (!agent || agent.steps.length === 0) return;
229 | 
230 |         summaryInflightRef.current[agentId] = true;
231 | 
232 |         try {
233 |             const recentSteps = agent.steps.slice(-5).map((step) => ({
234 |                 type: step.type,
235 |                 content: step.content.slice(-2000),
236 |             }));
237 | 
238 |             const resp = await summarizeAgent({
239 |                 agent_id: agentId,
240 |                 history: recentSteps,
241 |             });
242 | 
243 |             addAgentInsight(agentId, {
244 |                 summary: resp.summary,
245 |                 chart: resp.chart,
246 |             });
247 |         } catch (err) {
248 |             console.warn("Failed to summarize agent", agentId, err);
249 |         } finally {
250 |             summaryInflightRef.current[agentId] = false;
251 |         }
252 |     };
253 | 
254 |     const scheduleAgentSummary = (agentId: string) => {
255 |         if (!agentId) return;
256 | 
257 |         // debounce to wait for the end of a thought stream
258 |         const timers = summaryTimersRef.current;
259 |         if (timers[agentId]) {
260 |             clearTimeout(timers[agentId]!);
261 |         }
262 | 
263 |         timers[agentId] = setTimeout(() => runAgentSummary(agentId), 900);
264 |     };
265 | 
266 |     const startExperiment = async (
267 |         mode: "single" | "orchestrator",
268 |         config: {
269 |             task: string;
270 |             gpu?: string;
271 |             model?: string;
272 |             num_agents?: number;
273 |             max_rounds?: number;
274 |             max_parallel?: number;
275 |             test_mode?: boolean;
276 |         }
277 |     ) => {
278 |         // Reset any pending sidebar summary timers between runs
279 |         Object.values(summaryTimersRef.current).forEach((timer) => timer && clearTimeout(timer));
280 |         summaryTimersRef.current = {};
281 |         summaryInflightRef.current = {};
282 | 
283 |         setIsRunning(true);
284 |         setError(null);
285 |         setAgents({});
286 |         setOrchestrator({ thoughts: [], plan: [], timeline: [], status: "running" });
287 | 
288 |         try {
289 |             const endpoint = mode === "single"
290 |                 ? "/api/experiments/single/stream"
291 |                 : "/api/experiments/orchestrator/stream";
292 | 
293 |             const payload = mode === "single"
294 |                 ? { task: config.task, gpu: config.gpu, model: config.model, test_mode: config.test_mode }
295 |                 : {
296 |                     task: config.task,
297 |                     gpu: config.gpu,
298 |                     model: config.model,
299 |                     num_agents: config.num_agents || 3,
300 |                     max_rounds: config.max_rounds || 3,
301 |                     max_parallel: config.max_parallel || 2,
302 |                     test_mode: config.test_mode
303 |                 };
304 | 
305 |             await streamExperiment(
306 |                 endpoint,
307 |                 payload,
308 |                 (event) => {
309 |                     setLogs((prev) => [...prev, event]);
310 | 
311 |                     // Check for subprocess completion with error
312 |                     if (event.type === "summary" && event.exit_code !== 0) {
313 |                         // Find any error messages from recent logs (check both stderr and stdout for tracebacks)
314 |                         setLogs((prevLogs) => {
315 |                             // Look for stderr first
316 |                             const recentStderr = prevLogs
317 |                                 .filter((l) => l.stream === "stderr" && l.plain)
318 |                                 .slice(-10)
319 |                                 .map((l) => l.plain?.trim())
320 |                                 .filter(Boolean)
321 |                                 .join("\n");
322 | 
323 |                             // Also check stdout for error-like content (tracebacks, Fatal Error, etc.)
324 |                             const recentStdout = prevLogs
325 |                                 .filter((l) => l.stream === "stdout" && l.plain &&
326 |                                     (l.plain.includes("Error") || l.plain.includes("Traceback") || l.plain.includes("Exception")))
327 |                                 .slice(-10)
328 |                                 .map((l) => l.plain?.trim())
329 |                                 .filter(Boolean)
330 |                                 .join("\n");
331 | 
332 |                             // If no specific error found, show last few lines of any output
333 |                             const anyOutput = prevLogs
334 |                                 .filter((l) => l.type === "line" && l.plain)
335 |                                 .slice(-5)
336 |                                 .map((l) => l.plain?.trim())
337 |                                 .filter(Boolean)
338 |                                 .join("\n");
339 | 
340 |                             const errorMsg = recentStderr || recentStdout || anyOutput || `Process exited with code ${event.exit_code}. No output captured.`;
341 |                             setError(errorMsg);
342 |                             return prevLogs;
343 |                         });
344 |                     }
345 | 
346 |                     if (event.type === "line" && event.plain) {
347 |                         // Check for ::EVENT:: marker
348 |                         const eventIndex = event.plain.indexOf("::EVENT::");
349 |                         if (eventIndex !== -1) {
350 |                             try {
351 |                                 const jsonStr = event.plain.substring(eventIndex + "::EVENT::".length);
352 |                                 const payload = JSON.parse(jsonStr);
353 | 
354 |                                 // Try to extract Agent ID from prefix if present: "[Agent 1] ::EVENT::..."
355 |                                 let inferredAgentId: string | undefined;
356 |                                 const prefix = event.plain.substring(0, eventIndex);
357 |                                 const match = prefix.match(/\[Agent (\d+)\]/);
358 |                                 if (match) {
359 |                                     inferredAgentId = match[1];
360 |                                 }
361 | 
362 |                                 handleStructuredEvent(payload, inferredAgentId);
363 |                             } catch (e) {
364 |                                 console.warn("Failed to parse structured event:", e);
365 |                             }
366 |                         }
367 |                     }
368 |                 },
369 |                 (err) => {
370 |                     setError(err.message);
371 |                     setIsRunning(false);
372 |                 },
373 |                 () => {
374 |                     setIsRunning(false);
375 |                 }
376 |             );
377 |         } catch (err) {
378 |             setError(err instanceof Error ? err.message : "Failed to start experiment");
379 |             setIsRunning(false);
380 |         }
381 |     };
382 | 
383 |     const handleStructuredEvent = (event: any, inferredAgentId?: string) => {
384 |         const { type, data } = event;
385 | 
386 |         switch (type) {
387 |             case "AGENT_START":
388 |                 updateAgent(data.agent_id, {
389 |                     status: "running",
390 |                     hypothesis: data.hypothesis,
391 |                     gpu: data.gpu,
392 |                 });
393 | 
394 |                 // Add agent to the current 'agents' timeline item if it exists, or create new one
395 |                 setOrchestrator((prev) => {
396 |                     const lastItem = prev.timeline[prev.timeline.length - 1];
397 |                     if (lastItem && lastItem.type === "agents") {
398 |                         // Check if agent is already in the list to avoid dupes
399 |                         if (lastItem.agentIds.includes(data.agent_id)) {
400 |                             return prev;
401 |                         }
402 |                         // Update the last item in place (immutably)
403 |                         const newTimeline = [...prev.timeline];
404 |                         newTimeline[newTimeline.length - 1] = {
405 |                             ...lastItem,
406 |                             agentIds: [...lastItem.agentIds, data.agent_id]
407 |                         };
408 |                         return { ...prev, timeline: newTimeline };
409 |                     } else {
410 |                         // Create new agents group
411 |                         return {
412 |                             ...prev,
413 |                             timeline: [
414 |                                 ...prev.timeline,
415 |                                 { type: "agents", agentIds: [data.agent_id], timestamp: Date.now() }
416 |                             ]
417 |                         };
418 |                     }
419 |                 });
420 |                 break;
421 | 
422 |             case "AGENT_THOUGHT":
423 |                 if (inferredAgentId) {
424 |                     addAgentStep(inferredAgentId, {
425 |                         type: "thought",
426 |                         content: data.thought,
427 |                     });
428 |                     scheduleAgentSummary(inferredAgentId);
429 |                 }
430 |                 break;
431 | 
432 |             case "AGENT_THOUGHT_STREAM":
433 |                 if (inferredAgentId && typeof data?.chunk === "string") {
434 |                     appendToLatestAgentStep(inferredAgentId, "thought", data.chunk);
435 |                     scheduleAgentSummary(inferredAgentId);
436 |                 }
437 |                 break;
438 | 
439 |             case "AGENT_TOOL":
440 |                 if (inferredAgentId) {
441 |                     addAgentStep(inferredAgentId, {
442 |                         type: "code",
443 |                         content: `${data.tool}(${JSON.stringify(data.args, null, 2)})`,
444 |                         metadata: { tool: data.tool, args: data.args },
445 |                     });
446 |                 }
447 |                 break;
448 | 
449 |             case "AGENT_TOOL_RESULT":
450 |                 if (inferredAgentId) {
451 |                     // Update the latest step if it's a result block (from streaming),
452 |                     // otherwise create a new one.
453 |                     setAgents((prev) => {
454 |                         const current = prev[inferredAgentId];
455 |                         if (!current) return prev;
456 | 
457 |                         const steps = [...current.steps];
458 |                         const lastStep = steps[steps.length - 1];
459 | 
460 |                         if (lastStep && lastStep.type === "result") {
461 |                             // Update existing result block with the final full content
462 |                             steps[steps.length - 1] = {
463 |                                 ...lastStep,
464 |                                 content: data.result,
465 |                                 metadata: { ...lastStep.metadata, tool: data.tool }
466 |                             };
467 |                         } else {
468 |                             // Create new result block
469 |                             steps.push({
470 |                                 id: Math.random().toString(36).substring(7),
471 |                                 type: "result",
472 |                                 content: data.result,
473 |                                 metadata: { tool: data.tool },
474 |                                 timestamp: Date.now(),
475 |                             });
476 |                         }
477 | 
478 |                         return {
479 |                             ...prev,
480 |                             [inferredAgentId]: { ...current, steps }
481 |                         };
482 |                     });
483 | 
484 |                     scheduleAgentSummary(inferredAgentId);
485 |                 }
486 |                 break;
487 | 
488 |             case "AGENT_STREAM":
489 |                 if (inferredAgentId && typeof data?.chunk === "string") {
490 |                     // Stream incremental sandbox output into the latest result cell.
491 |                     // NotebookCell already handles carriage returns (\r) to render
492 |                     // tqdm-style progress bars cleanly.
493 |                     appendToLatestAgentStep(inferredAgentId, "result", data.chunk);
494 |                 }
495 |                 break;
496 | 
497 |             case "AGENT_COMPLETE":
498 |                 updateAgent(data.agent_id, {
499 |                     status: "completed",
500 |                     exitCode: data.exit_code,
501 |                 });
502 |                 scheduleAgentSummary(data.agent_id);
503 |                 break;
504 | 
505 |             case "ORCH_THOUGHT":
506 |                 setOrchestrator((prev) => ({
507 |                     ...prev,
508 |                     thoughts: [...prev.thoughts, data.thought],
509 |                     timeline: [
510 |                         ...prev.timeline,
511 |                         { type: "thought", content: data.thought, timestamp: Date.now() }
512 |                     ]
513 |                 }));
514 |                 break;
515 | 
516 |             case "ORCH_THOUGHT_STREAM":
517 |                 if (typeof data?.chunk === "string") {
518 |                     appendToLatestOrchestratorStep("thought", data.chunk);
519 |                 }
520 |                 break;
521 | 
522 |             case "ORCH_PAPER":
523 |                 // Capture any charts that agents have produced so we can surface them alongside the paper.
524 |                 const charts: ChartSpec[] = Object.values(agentsRef.current)
525 |                     .flatMap((agent) => (agent.insights || []).map((insight) => insight.chart))
526 |                     .filter(Boolean) as ChartSpec[];
527 | 
528 |                 // Deduplicate loosely by title + type + first series name + length of labels.
529 |                 const seen = new Set<string>();
530 |                 const uniqueCharts: ChartSpec[] = [];
531 |                 for (const chart of charts) {
532 |                     const key = [
533 |                         chart.title || "untitled",
534 |                         chart.type,
535 |                         chart.series?.[0]?.name || "series",
536 |                         chart.labels?.length || 0,
537 |                         chart.series?.[0]?.values?.length || 0,
538 |                     ].join("|");
539 |                     if (seen.has(key)) continue;
540 |                     seen.add(key);
541 |                     uniqueCharts.push(chart);
542 |                 }
543 | 
544 |                 setOrchestrator((prev) => ({
545 |                     ...prev,
546 |                     timeline: [
547 |                         ...prev.timeline,
548 |                         {
549 |                             type: "paper",
550 |                             content: data.content,
551 |                             charts: uniqueCharts.slice(0, 6), // keep it concise
552 |                             timestamp: Date.now(),
553 |                         },
554 |                     ],
555 |                 }));
556 |                 break;
557 | 
558 |             case "ORCH_TOOL":
559 |                 // We could also track orchestrator steps if we wanted a notebook for it
560 |                 break;
561 |         }
562 |     };
563 | 
564 |     // We need a way to parse the agent ID from the line if it exists.
565 |     // The orchestrator prefixes: `[Agent {id}] `
566 | 
567 |     const clearError = () => setError(null);
568 | 
569 |     return {
570 |         isRunning,
571 |         logs,
572 |         agents,
573 |         orchestrator,
574 |         error,
575 |         startExperiment,
576 |         clearError,
577 |     };
578 | }
579 | 


--------------------------------------------------------------------------------
/frontend/src/components/LabNotebook.tsx:
--------------------------------------------------------------------------------
  1 | import { useState, useEffect, useRef } from "react";
  2 | import { Loader2, Play } from "lucide-react";
  3 | import { motion } from "framer-motion";
  4 | import { useExperiment } from "@/lib/useExperiment";
  5 | import { FindingsRail } from "./FindingsRail";
  6 | import { AgentNotebook } from "./Notebook/AgentNotebook";
  7 | import { ResearchPaper } from "./Notebook/ResearchPaper";
  8 | import { cn } from "@/lib/utils";
  9 | import { StreamingMarkdown } from "./StreamingMarkdown";
 10 | import { CredentialPrompt, CredentialFormState } from "./CredentialPrompt";
 11 | import { CredentialStatus, fetchCredentialStatus, saveCredentials } from "@/lib/api";
 12 | 
 13 | type PendingRun = {
 14 |   mode: "single" | "orchestrator";
 15 |   config: {
 16 |     task: string;
 17 |     gpu?: string;
 18 |     model?: string;
 19 |     num_agents?: number;
 20 |     max_rounds?: number;
 21 |     max_parallel?: number;
 22 |     test_mode?: boolean;
 23 |   };
 24 | };
 25 | 
 26 | export function LabNotebook() {
 27 |   const { isRunning, agents, orchestrator, error: experimentError, startExperiment, clearError } = useExperiment();
 28 |   const [task, setTask] = useState("");
 29 |   const [mode, setMode] = useState<"single" | "orchestrator">("orchestrator");
 30 |   const [testMode, setTestMode] = useState(false);
 31 |   const bottomRef = useRef<HTMLDivElement>(null);
 32 |   const prevTimelineLengthRef = useRef(0);
 33 |   const [credentialStatus, setCredentialStatus] = useState<CredentialStatus | null>(null);
 34 |   const [credentialForm, setCredentialForm] = useState<CredentialFormState>({
 35 |     googleApiKey: "",
 36 |     anthropicApiKey: "",
 37 |     modalTokenId: "",
 38 |     modalTokenSecret: "",
 39 |   });
 40 |   const [selectedModel, setSelectedModel] = useState<"gemini-3-pro-preview" | "claude-opus-4-5">("gemini-3-pro-preview");
 41 |   const [showCredentialPrompt, setShowCredentialPrompt] = useState(false);
 42 |   const [pendingRun, setPendingRun] = useState<PendingRun | null>(null);
 43 |   const [isCheckingCredentials, setIsCheckingCredentials] = useState(false);
 44 |   const [isSavingCredentials, setIsSavingCredentials] = useState(false);
 45 |   const [prereqError, setPrereqError] = useState<string | null>(null);
 46 |   const [credentialPromptError, setCredentialPromptError] = useState<string | null>(null);
 47 | 
 48 |   // Check credentials once on load so we can prompt proactively.
 49 |   useEffect(() => {
 50 |     fetchCredentialStatus()
 51 |       .then(setCredentialStatus)
 52 |       .catch(() => {
 53 |         // silently ignore so we don't block the UI if the backend isn't ready yet
 54 |       });
 55 |   }, []);
 56 | 
 57 |   // Auto-scroll effect
 58 |   useEffect(() => {
 59 |     const currentLength = orchestrator.timeline.length;
 60 |     const prevLength = prevTimelineLengthRef.current;
 61 | 
 62 |     if (currentLength > prevLength) {
 63 |       const lastItem = orchestrator.timeline[currentLength - 1];
 64 |       if (lastItem.type === "agents" || lastItem.type === "paper" || currentLength === 1) {
 65 |         // Scroll slightly above the new element to keep context
 66 |         // We do this by scrolling to the bottom ref, but with 'start' block alignment if possible,
 67 |         // or just letting the padding handle it.
 68 |         // Actually, let's scroll to the *element itself* if we could, but since we use bottomRef,
 69 |         // let's just scroll smoothly to it. 
 70 |         // The user said it "goes a little too far", implying it might be scrolling past the top of the new content.
 71 |         // Or maybe it scrolls so the bottom is at the bottom of the screen?
 72 |         // "scrollIntoView" aligns the element to the top or bottom. 
 73 |         
 74 |         // Let's try aligning the bottomRef to the 'end' of the view, but give it some breathing room.
 75 |         bottomRef.current?.scrollIntoView({ behavior: "smooth", block: "end" });
 76 |       }
 77 |     }
 78 |     
 79 |     prevTimelineLengthRef.current = currentLength;
 80 |   }, [orchestrator.timeline]);
 81 | 
 82 |   const handleStart = async () => {
 83 |     if (!task.trim() || isCheckingCredentials) return;
 84 | 
 85 |     const config = {
 86 |       task,
 87 |       gpu: "any",
 88 |       model: selectedModel,
 89 |       num_agents: 3,
 90 |       max_rounds: 3,
 91 |       max_parallel: 2,
 92 |       test_mode: testMode,
 93 |     };
 94 | 
 95 |     setPrereqError(null);
 96 |     setCredentialPromptError(null);
 97 |     setIsCheckingCredentials(true);
 98 | 
 99 |     try {
100 |       const status = await fetchCredentialStatus();
101 |       setCredentialStatus(status);
102 | 
103 |       // Check if the required key for the selected model is available
104 |       const needsGoogleKey = selectedModel === "gemini-3-pro-preview" && !status.hasGoogleApiKey;
105 |       const needsAnthropicKey = selectedModel === "claude-opus-4-5" && !status.hasAnthropicApiKey;
106 |       const needsModalToken = !status.hasModalToken;
107 | 
108 |       if (needsGoogleKey || needsAnthropicKey || needsModalToken) {
109 |         setPendingRun({ mode, config });
110 |         setShowCredentialPrompt(true);
111 |         return;
112 |       }
113 | 
114 |       startExperiment(mode, config);
115 |     } catch (err) {
116 |       setPrereqError(err instanceof Error ? err.message : "Unable to verify API keys.");
117 |     } finally {
118 |       setIsCheckingCredentials(false);
119 |     }
120 |   };
121 | 
122 |   const handleCredentialFieldChange = (field: keyof CredentialFormState, value: string) => {
123 |     setCredentialForm((prev) => ({ ...prev, [field]: value }));
124 |   };
125 | 
126 |   const handleSaveCredentials = async () => {
127 |     setCredentialPromptError(null);
128 |     setIsSavingCredentials(true);
129 | 
130 |     try {
131 |       const status = await saveCredentials({
132 |         googleApiKey: credentialForm.googleApiKey || undefined,
133 |         anthropicApiKey: credentialForm.anthropicApiKey || undefined,
134 |         modalTokenId: credentialForm.modalTokenId || undefined,
135 |         modalTokenSecret: credentialForm.modalTokenSecret || undefined,
136 |       });
137 |       setCredentialStatus(status);
138 | 
139 |       // Check if we have the required key for the selected model
140 |       const hasRequiredLLMKey = selectedModel === "gemini-3-pro-preview"
141 |         ? status.hasGoogleApiKey
142 |         : status.hasAnthropicApiKey;
143 | 
144 |       if (hasRequiredLLMKey && status.hasModalToken) {
145 |         setShowCredentialPrompt(false);
146 |         setCredentialForm({ googleApiKey: "", anthropicApiKey: "", modalTokenId: "", modalTokenSecret: "" });
147 |         const nextRun = pendingRun;
148 |         setPendingRun(null);
149 |         if (nextRun) {
150 |           startExperiment(nextRun.mode, nextRun.config);
151 |         }
152 |       } else {
153 |         const modelName = selectedModel === "gemini-3-pro-preview" ? "Google" : "Anthropic";
154 |         setCredentialPromptError(`We still need the ${modelName} API key and Modal token to start a run with the selected model.`);
155 |       }
156 |     } catch (err) {
157 |       setCredentialPromptError(err instanceof Error ? err.message : "Unable to save credentials.");
158 |     } finally {
159 |       setIsSavingCredentials(false);
160 |     }
161 |   };
162 | 
163 |   const handleCloseCredentialPrompt = () => {
164 |     setShowCredentialPrompt(false);
165 |     setPendingRun(null);
166 |   };
167 | 
168 |   const isStartDisabled = !task.trim() || isCheckingCredentials;
169 | 
170 |   return (
171 |     <div className="flex h-screen w-full bg-black font-sans text-[#f5f5f7] selection:bg-[#333] selection:text-white">
172 |       {/* Fixed API Keys Button - Top Right */}
173 |       <button
174 |         onClick={() => setShowCredentialPrompt(true)}
175 |         className="fixed top-4 right-4 z-50 flex items-center gap-2 px-3 py-2 rounded-lg bg-[#1d1d1f] border border-[#333] text-[#86868b] hover:text-white hover:border-[#555] transition-all duration-300"
176 |       >
177 |         <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
178 |           <path d="M21 2l-2 2m-7.61 7.61a5.5 5.5 0 1 1-7.778 7.778 5.5 5.5 0 0 1 7.777-7.777zm0 0L15.5 7.5m0 0l3 3L22 7l-3-3m-3.5 3.5L19 4" />
179 |         </svg>
180 |         <span className="text-xs font-medium">API Keys</span>
181 |       </button>
182 | 
183 |       <div className="flex-1 h-full overflow-hidden flex flex-col">
184 | 
185 |         {/* Main Content Area */}
186 |         <main className="flex-1 flex flex-col overflow-hidden relative">
187 | 
188 |         {/* Sticky Header for Active Research */}
189 |         {orchestrator.timeline.length > 0 && (
190 |             <div className="absolute top-0 left-0 right-0 z-50 bg-black/80 backdrop-blur-xl border-b border-white/5 animate-in fade-in slide-in-from-top-4 duration-500">
191 |                 <div className="max-w-5xl mx-auto px-8 py-4 flex items-center gap-4">
192 |                     <span className="text-[10px] font-medium text-[#424245] uppercase tracking-widest shrink-0">
193 |                         Objective
194 |                     </span>
195 |                     <p className="text-sm font-light text-[#e5e5e5] truncate">
196 |                         {task}
197 |                     </p>
198 |                 </div>
199 |             </div>
200 |         )}
201 |         
202 |         {/* Scrollable Timeline */}
203 |         <div className="flex-1 overflow-y-auto custom-scrollbar">
204 |             <div className="max-w-5xl mx-auto py-24 px-8 space-y-32">
205 |                 
206 |                 {/* Initial Input State (Only visible when timeline is empty, not running, and no error) */}
207 |                 {orchestrator.timeline.length === 0 && !isRunning && !experimentError && (
208 |                     <div className="min-h-[60vh] flex flex-col justify-center items-center space-y-12 animate-in fade-in duration-1000">
209 |                         <div className="space-y-6 text-center max-w-lg">
210 |                             <h1 className="text-4xl md:text-5xl font-light tracking-tight text-white">
211 |                                 Research Objective
212 |                             </h1>
213 |                             <p className="text-lg text-[#86868b] font-light leading-relaxed">
214 |                                 Describe your scientific query. The orchestrator will decompose it into hypotheses and launch autonomous agents to investigate.
215 |                             </p>
216 |                         </div>
217 | 
218 |                         <div className="w-full max-w-xl space-y-8">
219 |                             <div className="relative group">
220 |                                 <div className="absolute -inset-1 bg-gradient-to-r from-[#333] to-[#1d1d1f] rounded-2xl blur opacity-20 group-hover:opacity-40 transition duration-1000"></div>
221 |                                 <textarea
222 |                                     value={task}
223 |                                     onChange={(e) => setTask(e.target.value)}
224 |                                     disabled={isRunning}
225 |                                     placeholder="e.g., Investigate the scaling laws of sparse attention mechanisms..."
226 |                                     className="relative w-full h-32 bg-black border border-[#333] rounded-xl p-6 text-lg font-light text-white placeholder:text-[#333] focus:ring-0 focus:border-[#666] focus:outline-none resize-none leading-relaxed transition-all duration-300"
227 |                                 />
228 |                             </div>
229 | 
230 |                             <div className="flex items-center justify-between">
231 |                                 <div className="flex items-center gap-4">
232 |                                     <button
233 |                                         onClick={() => setTestMode(!testMode)}
234 |                                         className={cn(
235 |                                             "text-[10px] font-medium px-3 py-1.5 rounded-full transition-all duration-300 border border-transparent",
236 |                                             testMode 
237 |                                                 ? "bg-white text-black border-white" 
238 |                                                 : "bg-[#1d1d1f] text-[#86868b] hover:text-white border-[#333]"
239 |                                         )}
240 |                                     >
241 |                                         {testMode ? "TEST MODE" : "LIVE MODE"}
242 |                                     </button>
243 |                                     <div className="h-4 w-[1px] bg-[#333]" />
244 |                                     <select
245 |                                         value={mode}
246 |                                         onChange={(e) => setMode(e.target.value as "single" | "orchestrator")}
247 |                                         className="bg-transparent text-[#86868b] text-xs font-medium focus:outline-none cursor-pointer hover:text-white transition-colors"
248 |                                     >
249 |                                         <option value="single">Single Agent</option>
250 |                                         <option value="orchestrator">Agent Swarm</option>
251 |                                     </select>
252 |                                     <div className="h-4 w-[1px] bg-[#333]" />
253 |                                     <select
254 |                                         value={selectedModel}
255 |                                         onChange={(e) => setSelectedModel(e.target.value as "gemini-3-pro-preview" | "claude-opus-4-5")}
256 |                                         className="bg-transparent text-[#86868b] text-xs font-medium focus:outline-none cursor-pointer hover:text-white transition-colors"
257 |                                     >
258 |                                         <option value="gemini-3-pro-preview">Gemini 3 Pro</option>
259 |                                         <option value="claude-opus-4-5">Claude Opus 4.5</option>
260 |                                     </select>
261 |                                 </div>
262 | 
263 |                                 <div className="flex flex-col items-end gap-2">
264 |                                     <button
265 |                                         onClick={handleStart}
266 |                                         disabled={isStartDisabled}
267 |                                         className={cn(
268 |                                             "px-8 py-3 rounded-full text-xs font-medium tracking-widest uppercase transition-all duration-500 flex items-center gap-2",
269 |                                             isStartDisabled
270 |                                                 ? "bg-[#1d1d1f] text-[#333] cursor-not-allowed"
271 |                                                 : "bg-white text-black hover:bg-[#e5e5e5] hover:scale-105"
272 |                                         )}
273 |                                     >
274 |                                         {isCheckingCredentials ? (
275 |                                             <>
276 |                                                 <Loader2 className="w-3 h-3 animate-spin" />
277 |                                                 <span>Checking keys...</span>
278 |                                             </>
279 |                                         ) : (
280 |                                             <>
281 |                                                 <Play className="w-3 h-3 fill-current" />
282 |                                                 <span>Start Research</span>
283 |                                             </>
284 |                                         )}
285 |                                     </button>
286 |                                     {prereqError && (
287 |                                         <p className="text-xs text-red-300 text-right max-w-sm">
288 |                                             {prereqError}
289 |                                         </p>
290 |                                     )}
291 |                                 </div>
292 |                             </div>
293 |                         </div>
294 |                     </div>
295 |                 )}
296 | 
297 |                 {/* Error State (Visible when experiment failed) */}
298 |                 {experimentError && !isRunning && orchestrator.timeline.length === 0 && (
299 |                     <div className="min-h-[60vh] flex flex-col justify-center items-center space-y-8 animate-in fade-in duration-700">
300 |                         <div className="space-y-4 text-center max-w-lg">
301 |                             <div className="w-16 h-16 mx-auto rounded-full bg-red-500/10 border border-red-500/30 flex items-center justify-center">
302 |                                 <span className="text-2xl">⚠️</span>
303 |                             </div>
304 |                             <h2 className="text-xl font-light text-white tracking-wide">
305 |                                 Experiment Failed
306 |                             </h2>
307 |                             <p className="text-sm text-red-300 font-mono bg-red-500/10 border border-red-500/20 rounded-lg p-4">
308 |                                 {experimentError}
309 |                             </p>
310 |                             <p className="text-xs text-[#86868b]">
311 |                                 Check your API keys and try again. If using Claude Opus 4.5, make sure your Anthropic API key is set.
312 |                             </p>
313 |                             <button
314 |                                 onClick={() => clearError()}
315 |                                 className="mt-4 px-6 py-2 rounded-full text-xs font-medium tracking-widest uppercase transition-all duration-500 bg-white text-black hover:bg-[#e5e5e5] hover:scale-105"
316 |                             >
317 |                                 Try Again
318 |                             </button>
319 |                         </div>
320 |                     </div>
321 |                 )}
322 | 
323 |                 {/* Loading State (Visible when running but no timeline events yet) */}
324 |                 {orchestrator.timeline.length === 0 && isRunning && (
325 |                     <div className="min-h-[60vh] flex flex-col justify-center items-center space-y-8 animate-in fade-in duration-700">
326 |                         <div className="relative">
327 |                             <div className="absolute inset-0 bg-white/20 blur-xl rounded-full animate-pulse"></div>
328 |                             <div className="relative w-16 h-16 border-t-2 border-white rounded-full animate-spin"></div>
329 |                             <div className="absolute inset-0 flex items-center justify-center">
330 |                                 <div className="w-2 h-2 bg-white rounded-full animate-ping" />
331 |                             </div>
332 |                         </div>
333 |                         <div className="space-y-2 text-center">
334 |                             <h2 className="text-xl font-light text-white tracking-wide animate-pulse">
335 |                                 Initializing Research Environment
336 |                             </h2>
337 |                             <p className="text-sm text-[#86868b] font-mono">
338 |                                 Spinning up main agent...
339 |                             </p>
340 |                         </div>
341 |                     </div>
342 |                 )}
343 | 
344 |                 {/* Timeline Rendering */}
345 |                 {orchestrator.timeline.map((item, index) => {
346 |                     const key = item.timestamp ?? `${item.type}-${index}`;
347 |                     if (item.type === "thought") {
348 |                         return (
349 |                             <motion.div 
350 |                                 key={key} 
351 |                                 initial={{ opacity: 0, y: 20, filter: "blur(10px)" }}
352 |                                 animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
353 |                                 transition={{ duration: 0.8, ease: "easeOut" }}
354 |                                 className="w-full"
355 |                             >
356 |                                 <div className="pl-6 border-l border-[#333] py-2">
357 |                                     <span className="block text-[10px] font-medium text-[#424245] uppercase tracking-widest mb-3">
358 |                                         Orchestrator
359 |                                     </span>
360 |                                     <StreamingMarkdown
361 |                                         animateKey={key}
362 |                                         content={item.content}
363 |                                         markdownClassName="prose prose-invert prose-lg md:prose-xl max-w-none prose-p:text-[#d1d1d6] prose-p:font-light prose-p:leading-relaxed prose-strong:text-white prose-headings:text-white prose-code:text-[#d1d1d6] prose-pre:bg-[#1d1d1f] prose-pre:border prose-pre:border-[#333]"
364 |                                     />
365 |                                 </div>
366 |                             </motion.div>
367 |                         );
368 |                     } else if (item.type === "agents") {
369 |                         return (
370 |                             <motion.div 
371 |                                 key={key} 
372 |                                 initial={{ opacity: 0, y: 20, filter: "blur(10px)" }}
373 |                                 animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
374 |                                 transition={{ duration: 0.8, ease: "easeOut" }}
375 |                                 className="space-y-8"
376 |                             >
377 |                                 <div className="flex items-center gap-3">
378 |                                     <div className="h-[1px] w-8 bg-[#333]" />
379 |                                     <span className="text-[10px] font-medium text-[#424245] uppercase tracking-widest">
380 |                                         Sub-Agents Deployed
381 |                                     </span>
382 |                                     <div className="h-[1px] flex-1 bg-[#333]" />
383 |                                 </div>
384 |                                 <div className="grid grid-cols-1 xl:grid-cols-2 gap-6">
385 |                                     {item.agentIds.map((agentId) => {
386 |                                         const agent = agents[agentId];
387 |                                         if (!agent) return null;
388 |                                         return (
389 |                                             <div key={agentId} className="h-[600px]">
390 |                                                 <AgentNotebook agent={agent} />
391 |                                             </div>
392 |                                         );
393 |                                     })}
394 |                                 </div>
395 |                             </motion.div>
396 |                         );
397 |                     } else if (item.type === "paper") {
398 |                         return (
399 |                             <motion.div
400 |                                 key={key}
401 |                                 initial={{ opacity: 0, y: 20, filter: "blur(10px)" }}
402 |                                 animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
403 |                                 transition={{ duration: 0.8, ease: "easeOut" }}
404 |                             >
405 |                                 <ResearchPaper content={item.content} charts={item.charts} />
406 |                             </motion.div>
407 |                         );
408 |                     }
409 |                     return null;
410 |                 })}
411 |                 
412 |                 {/* Running Indicator at Bottom */}
413 |                 {isRunning && orchestrator.timeline.length > 0 && (
414 |                     <div className="flex justify-center py-12">
415 |                         <div className="flex items-center gap-3 px-4 py-2 rounded-full bg-[#1d1d1f] border border-[#333]">
416 |                             <div className="w-1.5 h-1.5 rounded-full bg-green-500 animate-pulse" />
417 |                             <span className="text-[10px] font-medium text-[#86868b] uppercase tracking-widest">
418 |                                 Orchestrating
419 |                             </span>
420 |                         </div>
421 |                     </div>
422 |                 )}
423 | 
424 |                 <div ref={bottomRef} className="h-10" />
425 |             </div>
426 |         </div>
427 |       </main>
428 | 
429 |       </div>
430 |       {/* Summaries rail on the right */}
431 |       <FindingsRail agents={agents} />
432 | 
433 |       {/* Minimal Fixed Header (Only visible when running) */}
434 |       {isRunning && (
435 |           <div className="fixed top-0 left-0 right-0 z-50 h-1 bg-gradient-to-r from-blue-500 via-purple-500 to-pink-500 animate-gradient-x" />
436 |       )}
437 | 
438 |       <CredentialPrompt
439 |         open={showCredentialPrompt}
440 |         status={credentialStatus}
441 |         selectedModel={selectedModel}
442 |         form={credentialForm}
443 |         onChange={handleCredentialFieldChange}
444 |         onSubmit={handleSaveCredentials}
445 |         onClose={handleCloseCredentialPrompt}
446 |         isSaving={isSavingCredentials}
447 |         error={credentialPromptError}
448 |       />
449 |     </div>
450 |   );
451 | }
452 | 


--------------------------------------------------------------------------------
/api_server.py:
--------------------------------------------------------------------------------
  1 | from __future__ import annotations
  2 | 
  3 | import json
  4 | import queue
  5 | import re
  6 | import subprocess
  7 | import sys
  8 | import threading
  9 | import os
 10 | from datetime import datetime, timezone
 11 | from pathlib import Path
 12 | from typing import Any, Dict, List, Optional, Literal
 13 | 
 14 | from dotenv import load_dotenv, set_key
 15 | from fastapi import FastAPI, HTTPException
 16 | from fastapi.responses import StreamingResponse, FileResponse
 17 | from fastapi.staticfiles import StaticFiles
 18 | from pydantic import BaseModel, Field
 19 | 
 20 | # Load environment variables from the repo's .env file so spawned processes inherit them.
 21 | BASE_DIR = Path(__file__).resolve().parent
 22 | ENV_PATH = BASE_DIR / ".env"
 23 | load_dotenv(ENV_PATH)
 24 | 
 25 | MAIN_PATH = BASE_DIR / "main.py"
 26 | 
 27 | # Regex for stripping ANSI escape sequences (Rich colour codes, etc.).
 28 | ANSI_ESCAPE_RE = re.compile(r"\x1B\[[0-?]*[ -/]*[@-~]")
 29 | 
 30 | 
 31 | def strip_ansi(text: str) -> str:
 32 |     """
 33 |     Remove ANSI colour / style escape sequences from terminal output.
 34 | 
 35 |     This is useful for building UIs that want plain text, while still
 36 |     retaining the original coloured output for advanced terminals.
 37 |     """
 38 |     return ANSI_ESCAPE_RE.sub("", text)
 39 | 
 40 | 
 41 | class UserCredentials(BaseModel):
 42 |     """API credentials passed per-request for multi-user deployments."""
 43 |     google_api_key: Optional[str] = Field(None, description="Google AI Studio API key")
 44 |     anthropic_api_key: Optional[str] = Field(None, description="Anthropic API key")
 45 |     modal_token_id: Optional[str] = Field(None, description="Modal token ID")
 46 |     modal_token_secret: Optional[str] = Field(None, description="Modal token secret")
 47 | 
 48 | 
 49 | class SingleExperimentRequest(BaseModel):
 50 |     """
 51 |     Request body for running a single-agent experiment.
 52 | 
 53 |     This directly maps to:
 54 |         python main.py "<task>" --mode single [--gpu GPU] [--model MODEL]
 55 |     """
 56 | 
 57 |     task: str = Field(
 58 |         ...,
 59 |         description=(
 60 |             "A short natural-language hypothesis to test. This is passed to the "
 61 |             "single research agent as the main experiment description."
 62 |         ),
 63 |         examples=[
 64 |             "Fine-tuning a small transformer on CIFAR-10 improves accuracy by more than 5%."
 65 |         ],
 66 |     )
 67 |     gpu: Optional[str] = Field(
 68 |         None,
 69 |         description=(
 70 |             "Optional GPU type to request for the Modal sandbox. "
 71 |             "Examples: 'T4', 'A10G', 'A100', 'any'. "
 72 |             "If omitted, the system uses its default (CPU-only or configured GPU)."
 73 |         ),
 74 |         examples=["T4"],
 75 |     )
 76 |     model: str = Field(
 77 |         "gemini-3-pro-preview",
 78 |         description=(
 79 |             "The LLM model to use for the experiment. "
 80 |             "Options: 'gemini-3-pro-preview' or 'claude-opus-4-5'."
 81 |         ),
 82 |         examples=["gemini-3-pro-preview", "claude-opus-4-5"],
 83 |     )
 84 |     test_mode: bool = Field(
 85 |         False,
 86 |         description="If true, runs in test mode with mock data (no LLM/GPU usage).",
 87 |     )
 88 |     credentials: Optional[UserCredentials] = Field(
 89 |         None,
 90 |         description="User-provided API credentials. If not provided, falls back to server environment.",
 91 |     )
 92 | 
 93 | 
 94 | class OrchestratorExperimentRequest(BaseModel):
 95 |     """
 96 |     Request body for running the multi-agent orchestrator.
 97 | 
 98 |     This maps to:
 99 |         python main.py "<task>" --mode orchestrator \\
100 |             --num-agents N --max-rounds R --max-parallel P [--gpu GPU] [--model MODEL]
101 |     """
102 | 
103 |     task: str = Field(
104 |         ...,
105 |         description=(
106 |             "High-level research question for the orchestrator to investigate. "
107 |             "The orchestrator will decompose this into multiple hypotheses and "
108 |             "launch single-agent experiments as needed."
109 |         ),
110 |         examples=[
111 |             "Characterize the scaling behaviour of depth vs width in small transformers."
112 |         ],
113 |     )
114 |     gpu: Optional[str] = Field(
115 |         None,
116 |         description=(
117 |             "Default GPU hint for experiments spawned by the orchestrator "
118 |             "(e.g. 'T4', 'A10G', 'A100', 'any'). If omitted, falls back to the "
119 |             "host default (CPU-only or configured GPU)."
120 |         ),
121 |         examples=["A10G"],
122 |     )
123 |     model: str = Field(
124 |         "gemini-3-pro-preview",
125 |         description=(
126 |             "The LLM model to use for the experiment. "
127 |             "Options: 'gemini-3-pro-preview' or 'claude-opus-4-5'."
128 |         ),
129 |         examples=["gemini-3-pro-preview", "claude-opus-4-5"],
130 |     )
131 |     num_agents: int = Field(
132 |         3,
133 |         ge=1,
134 |         le=16,
135 |         description=(
136 |             "How many distinct single-agent researchers to launch in the first wave. "
137 |             "This is passed as --num-agents."
138 |         ),
139 |     )
140 |     max_rounds: int = Field(
141 |         3,
142 |         ge=1,
143 |         le=10,
144 |         description=(
145 |             "Maximum number of orchestration rounds (waves of experiments). "
146 |             "This is passed as --max-rounds."
147 |         ),
148 |     )
149 |     max_parallel: int = Field(
150 |         2,
151 |         ge=1,
152 |         le=16,
153 |         description=(
154 |             "Maximum number of experiments to run in parallel in a single wave. "
155 |             "This is passed as --max-parallel."
156 |         ),
157 |     )
158 |     test_mode: bool = Field(
159 |         False,
160 |         description="If true, runs in test mode with mock data (no LLM/GPU usage).",
161 |     )
162 |     credentials: Optional[UserCredentials] = Field(
163 |         None,
164 |         description="User-provided API credentials. If not provided, falls back to server environment.",
165 |     )
166 | 
167 | 
168 | class SummaryHistoryItem(BaseModel):
169 |     """Minimal view of an agent step for sidebar summarization."""
170 | 
171 |     type: Literal["thought", "code", "result", "text"] = Field(
172 |         ...,
173 |         description="Type of step (kept small to control context size).",
174 |     )
175 |     content: str = Field(
176 |         ..., description="Truncated text content of the step (agent thought or tool output)."
177 |     )
178 | 
179 | 
180 | class AgentSummaryRequest(BaseModel):
181 |     """Request body for Gemini-lite sidebar summaries."""
182 | 
183 |     agent_id: str = Field(..., description="Sub-agent identifier")
184 |     history: List[SummaryHistoryItem] = Field(
185 |         ..., description="Last ~5 steps for this agent (already truncated on client)."
186 |     )
187 | 
188 | 
189 | class AgentSummaryResponse(BaseModel):
190 |     """Shape returned to the frontend for sidebar rendering."""
191 | 
192 |     summary: str = Field(..., description="Short markdown-friendly finding")
193 |     chart: Optional[Dict[str, Any]] = Field(
194 |         None,
195 |         description=(
196 |             "Optional chart spec with keys: title, type(line|bar), labels, series. "
197 |             "Omitted if no obvious numeric progression."
198 |         ),
199 |     )
200 | 
201 | 
202 | class CredentialStatus(BaseModel):
203 |     """Report which required API credentials are present."""
204 | 
205 |     has_google_api_key: bool = Field(
206 |         ...,
207 |         description="True when GOOGLE_API_KEY is set to a non-placeholder value.",
208 |     )
209 |     has_anthropic_api_key: bool = Field(
210 |         ...,
211 |         description="True when ANTHROPIC_API_KEY is set to a non-placeholder value.",
212 |     )
213 |     has_modal_token: bool = Field(
214 |         ...,
215 |         description="True when both MODAL_TOKEN_ID and MODAL_TOKEN_SECRET are set.",
216 |     )
217 | 
218 | 
219 | class CredentialUpdateRequest(BaseModel):
220 |     """Payload for setting API credentials via the UI."""
221 | 
222 |     google_api_key: Optional[str] = Field(
223 |         None, description="Full Google API key from AI Studio"
224 |     )
225 |     anthropic_api_key: Optional[str] = Field(
226 |         None, description="Anthropic API key from https://console.anthropic.com"
227 |     )
228 |     modal_token_id: Optional[str] = Field(
229 |         None, description="Modal token ID from https://modal.com/settings/tokens"
230 |     )
231 |     modal_token_secret: Optional[str] = Field(
232 |         None, description="Modal token secret from https://modal.com/settings/tokens"
233 |     )
234 | 
235 | 
236 | class ProcessSummary(BaseModel):
237 |     """
238 |     Structured view of a completed CLI run.
239 | 
240 |     The stdout/stderr fields preserve all Rich formatting escape codes,
241 |     while the *_plain variants provide the same content with ANSI codes stripped
242 |     for easy rendering in front-ends.
243 |     """
244 | 
245 |     mode: Literal["single", "orchestrator"] = Field(
246 |         ...,
247 |         description="Which execution mode was used.",
248 |     )
249 |     task: str = Field(
250 |         ...,
251 |         description="Original task/hypothesis passed to main.py.",
252 |     )
253 |     gpu: Optional[str] = Field(
254 |         None,
255 |         description="GPU hint passed to main.py (if any).",
256 |     )
257 |     command: List[str] = Field(
258 |         ...,
259 |         description="Exact command invoked by the API to run the experiment.",
260 |     )
261 |     started_at: datetime = Field(
262 |         ...,
263 |         description="UTC timestamp when the subprocess started.",
264 |     )
265 |     finished_at: datetime = Field(
266 |         ...,
267 |         description="UTC timestamp when the subprocess finished.",
268 |     )
269 |     duration_seconds: float = Field(
270 |         ...,
271 |         description="Wall-clock run duration in seconds.",
272 |     )
273 |     exit_code: int = Field(
274 |         ...,
275 |         description="Subprocess exit code. Zero usually indicates success.",
276 |     )
277 |     stdout: str = Field(
278 |         ...,
279 |         description="Raw stdout produced by main.py (including ANSI colour codes).",
280 |     )
281 |     stderr: str = Field(
282 |         ...,
283 |         description="Raw stderr produced by main.py (including ANSI colour codes).",
284 |     )
285 |     stdout_plain: str = Field(
286 |         ...,
287 |         description="Stdout with ANSI escape codes stripped for simple rendering.",
288 |     )
289 |     stderr_plain: str = Field(
290 |         ...,
291 |         description="Stderr with ANSI escape codes stripped for simple rendering.",
292 |     )
293 | 
294 | 
295 | app = FastAPI(
296 |     title="AI Researcher API",
297 |     description=(
298 |         "Thin HTTP wrapper around the existing CLI-based AI Researcher agents.\n\n"
299 |         "The API does not reimplement any research logic; it simply shells out "
300 |         "to `main.py` and returns everything the CLI prints so that a front-end "
301 |         "can visualise it in rich ways."
302 |     ),
303 |     version="0.1.0",
304 | )
305 | 
306 | from fastapi.middleware.cors import CORSMiddleware
307 | 
308 | # Optional, lightweight summarizer (kept outside agent logic)
309 | from insights import summarize_agent_findings
310 | 
311 | # For Railway/production: allow all origins, or be more specific
312 | app.add_middleware(
313 |     CORSMiddleware,
314 |     allow_origins=["*"],
315 |     allow_credentials=True,
316 |     allow_methods=["*"],
317 |     allow_headers=["*"],
318 | )
319 | 
320 | # Serve frontend static files in production
321 | FRONTEND_DIST = BASE_DIR / "frontend" / "dist"
322 | 
323 | def _env_value_present(value: Optional[str]) -> bool:
324 |     """Treat empty or placeholder values as missing."""
325 |     if value is None:
326 |         return False
327 |     cleaned = value.strip()
328 |     if not cleaned:
329 |         return False
330 | 
331 |     lower = cleaned.lower()
332 |     # Ignore common placeholder patterns (e.g., "your_google_api_key_here").
333 |     if lower.startswith("your_") or lower.endswith("_here"):
334 |         return False
335 |     if lower in {"changeme", "example"}:
336 |         return False
337 |     return True
338 | 
339 | 
340 | def _persist_env(key: str, value: str) -> None:
341 |     """Persist a credential to both the running process and the .env file."""
342 |     os.environ[key] = value
343 |     set_key(str(ENV_PATH), key, value)
344 | 
345 | 
346 | def _credential_status() -> CredentialStatus:
347 |     """Summarize which credentials are available."""
348 |     has_google = _env_value_present(os.environ.get("GOOGLE_API_KEY"))
349 |     has_anthropic = _env_value_present(os.environ.get("ANTHROPIC_API_KEY"))
350 |     has_modal_id = _env_value_present(os.environ.get("MODAL_TOKEN_ID"))
351 |     has_modal_secret = _env_value_present(os.environ.get("MODAL_TOKEN_SECRET"))
352 |     return CredentialStatus(
353 |         has_google_api_key=has_google,
354 |         has_anthropic_api_key=has_anthropic,
355 |         has_modal_token=has_modal_id and has_modal_secret,
356 |     )
357 | 
358 | 
359 | def _ensure_main_exists() -> None:
360 |     """
361 |     Verify that main.py exists at the expected location.
362 | 
363 |     If not, raise an HTTPException so callers get a clear error.
364 |     """
365 |     if not MAIN_PATH.exists():
366 |         raise HTTPException(
367 |             status_code=500,
368 |             detail=f"main.py not found at expected path: {MAIN_PATH}",
369 |         )
370 | 
371 | 
372 | def _build_single_command(req: SingleExperimentRequest) -> List[str]:
373 |     """
374 |     Build the command to run a single-agent experiment via main.py.
375 |     """
376 |     cmd: List[str] = [
377 |         sys.executable,
378 |         str(MAIN_PATH),
379 |         req.task,
380 |         "--mode",
381 |         "single",
382 |         "--model",
383 |         req.model,
384 |     ]
385 |     if req.gpu:
386 |         cmd.extend(["--gpu", req.gpu])
387 |     if req.test_mode:
388 |         cmd.append("--test-mode")
389 |     return cmd
390 | 
391 | 
392 | def _build_orchestrator_command(req: OrchestratorExperimentRequest) -> List[str]:
393 |     """
394 |     Build the command to run the orchestrator via main.py.
395 |     """
396 |     cmd: List[str] = [
397 |         sys.executable,
398 |         str(MAIN_PATH),
399 |         req.task,
400 |         "--mode",
401 |         "orchestrator",
402 |         "--model",
403 |         req.model,
404 |         "--num-agents",
405 |         str(req.num_agents),
406 |         "--max-rounds",
407 |         str(req.max_rounds),
408 |         "--max-parallel",
409 |         str(req.max_parallel),
410 |     ]
411 |     if req.gpu:
412 |         cmd.extend(["--gpu", req.gpu])
413 |     if req.test_mode:
414 |         cmd.append("--test-mode")
415 |     return cmd
416 | 
417 | 
418 | def _run_and_capture(
419 |     cmd: List[str],
420 |     *,
421 |     mode: Literal["single", "orchestrator"],
422 |     task: str,
423 |     gpu: Optional[str],
424 | ) -> ProcessSummary:
425 |     """
426 |     Run `main.py` as a subprocess and capture all of its stdout/stderr.
427 | 
428 |     This leaves the underlying CLI behaviour untouched and simply wraps it.
429 |     """
430 |     _ensure_main_exists()
431 | 
432 |     started_at = datetime.now(timezone.utc)
433 | 
434 |     # Enable structured event emission in the child process so the frontend
435 |     # can consume ::EVENT::-prefixed messages.
436 |     env = dict(os.environ)
437 |     env["AI_RESEARCHER_ENABLE_EVENTS"] = "1"
438 | 
439 |     proc = subprocess.Popen(
440 |         cmd,
441 |         stdout=subprocess.PIPE,
442 |         stderr=subprocess.PIPE,
443 |         text=True,
444 |         bufsize=1,
445 |         env=env,
446 |     )
447 | 
448 |     stdout_chunks: List[str] = []
449 |     stderr_chunks: List[str] = []
450 | 
451 |     def _reader(stream, chunks: List[str]) -> None:
452 |         for line in stream:
453 |             chunks.append(line)
454 | 
455 |     t_out = threading.Thread(
456 |         target=_reader, args=(proc.stdout, stdout_chunks), daemon=True
457 |     )
458 |     t_err = threading.Thread(
459 |         target=_reader, args=(proc.stderr, stderr_chunks), daemon=True
460 |     )
461 | 
462 |     t_out.start()
463 |     t_err.start()
464 | 
465 |     exit_code = proc.wait()
466 |     t_out.join()
467 |     t_err.join()
468 | 
469 |     finished_at = datetime.now(timezone.utc)
470 | 
471 |     stdout_text = "".join(stdout_chunks)
472 |     stderr_text = "".join(stderr_chunks)
473 | 
474 |     return ProcessSummary(
475 |         mode=mode,
476 |         task=task,
477 |         gpu=gpu,
478 |         command=cmd,
479 |         started_at=started_at,
480 |         finished_at=finished_at,
481 |         duration_seconds=(finished_at - started_at).total_seconds(),
482 |         exit_code=exit_code,
483 |         stdout=stdout_text,
484 |         stderr=stderr_text,
485 |         stdout_plain=strip_ansi(stdout_text),
486 |         stderr_plain=strip_ansi(stderr_text),
487 |     )
488 | 
489 | 
490 | def _stream_subprocess(
491 |     cmd: List[str],
492 |     *,
493 |     meta: Dict[str, Any],
494 |     credentials: Optional[UserCredentials] = None,
495 | ) -> StreamingResponse:
496 |     """
497 |     Stream stdout/stderr from `main.py` as newline-delimited JSON (NDJSON).
498 | 
499 |     Each line of output is sent as:
500 |         {
501 |           "type": "line",
502 |           "stream": "stdout" | "stderr",
503 |           "timestamp": "<ISO-8601>",
504 |           "raw": "<raw line>",
505 |           "plain": "<line without ANSI>",
506 |           ...meta
507 |         }
508 | 
509 |     When the process finishes, a final summary event is sent:
510 |         {
511 |           "type": "summary",
512 |           "exit_code": <int>,
513 |           "started_at": "<ISO-8601>",
514 |           "finished_at": "<ISO-8601>",
515 |           "duration_seconds": <float>,
516 |           ...meta
517 |         }
518 |     """
519 |     _ensure_main_exists()
520 | 
521 |     started_at = datetime.now(timezone.utc)
522 | 
523 |     # Enable structured event emission in the child process so the frontend
524 |     # can consume ::EVENT::-prefixed messages.
525 |     env = dict(os.environ)
526 |     env["AI_RESEARCHER_ENABLE_EVENTS"] = "1"
527 | 
528 |     # Override with user-provided credentials if present
529 |     if credentials:
530 |         if credentials.google_api_key:
531 |             env["GOOGLE_API_KEY"] = credentials.google_api_key
532 |             print(f"[DEBUG] Set GOOGLE_API_KEY from request (len={len(credentials.google_api_key)})", file=sys.stderr)
533 |         if credentials.anthropic_api_key:
534 |             env["ANTHROPIC_API_KEY"] = credentials.anthropic_api_key
535 |             print(f"[DEBUG] Set ANTHROPIC_API_KEY from request (len={len(credentials.anthropic_api_key)})", file=sys.stderr)
536 |         if credentials.modal_token_id:
537 |             env["MODAL_TOKEN_ID"] = credentials.modal_token_id
538 |             print(f"[DEBUG] Set MODAL_TOKEN_ID from request (len={len(credentials.modal_token_id)})", file=sys.stderr)
539 |         if credentials.modal_token_secret:
540 |             env["MODAL_TOKEN_SECRET"] = credentials.modal_token_secret
541 |             print(f"[DEBUG] Set MODAL_TOKEN_SECRET from request (len={len(credentials.modal_token_secret)})", file=sys.stderr)
542 |     else:
543 |         print("[DEBUG] No credentials in request, using environment", file=sys.stderr)
544 | 
545 |     proc = subprocess.Popen(
546 |         cmd,
547 |         stdout=subprocess.PIPE,
548 |         stderr=subprocess.PIPE,
549 |         text=True,
550 |         bufsize=1,
551 |         env=env,
552 |     )
553 | 
554 |     # Queue is used to multiplex stdout and stderr into a single ordered stream.
555 |     q: "queue.Queue[Optional[Dict[str, Any]]]" = queue.Queue()
556 | 
557 |     def _push_line(stream, stream_name: str) -> None:
558 |         for line in stream:
559 |             event: Dict[str, Any] = {
560 |                 "type": "line",
561 |                 "stream": stream_name,
562 |                 "timestamp": datetime.now(timezone.utc).isoformat(),
563 |                 "raw": line,
564 |                 "plain": strip_ansi(line),
565 |             }
566 |             event.update(meta)
567 |             q.put(event)
568 | 
569 |     def _wait_for_exit() -> None:
570 |         exit_code = proc.wait()
571 |         finished_at = datetime.now(timezone.utc)
572 |         summary: Dict[str, Any] = {
573 |             "type": "summary",
574 |             "timestamp": finished_at.isoformat(),
575 |             "exit_code": exit_code,
576 |             "started_at": started_at.isoformat(),
577 |             "finished_at": finished_at.isoformat(),
578 |             "duration_seconds": (finished_at - started_at).total_seconds(),
579 |         }
580 |         summary.update(meta)
581 |         q.put(summary)
582 |         # Sentinel to tell the iterator to stop.
583 |         q.put(None)
584 | 
585 |     threading.Thread(
586 |         target=_push_line, args=(proc.stdout, "stdout"), daemon=True
587 |     ).start()
588 |     threading.Thread(
589 |         target=_push_line, args=(proc.stderr, "stderr"), daemon=True
590 |     ).start()
591 |     threading.Thread(target=_wait_for_exit, daemon=True).start()
592 | 
593 |     def event_iterator():
594 |         while True:
595 |             item = q.get()
596 |             if item is None:
597 |                 break
598 |             yield json.dumps(item, ensure_ascii=False) + "\n"
599 | 
600 |     return StreamingResponse(
601 |         event_iterator(),
602 |         media_type="application/x-ndjson",
603 |     )
604 | 
605 | 
606 | @app.get("/api/health", summary="Simple health probe")
607 | def health_check() -> Dict[str, Any]:
608 |     """
609 |     Lightweight health check.
610 | 
611 |     This does not call Gemini or Modal; it only verifies that `main.py`
612 |     exists on disk and that the API process can see it.
613 |     """
614 |     exists = MAIN_PATH.exists()
615 |     return {
616 |         "status": "ok" if exists else "error",
617 |         "main_py": str(MAIN_PATH),
618 |         "main_py_exists": exists,
619 |     }
620 | 
621 | 
622 | @app.get("/api/state", summary="Get global system state")
623 | def get_state() -> Dict[str, Any]:
624 |     """
625 |     Return the current global state of the orchestrator.
626 |     This is primarily to support legacy clients or status monitors.
627 |     """
628 |     # Import here to avoid circular imports if orchestrator imports api_server
629 |     try:
630 |         from orchestrator import _experiment_counter, _default_gpu
631 |         return {
632 |             "status": "active",
633 |             "experiments_run": _experiment_counter,
634 |             "default_gpu": _default_gpu,
635 |         }
636 |     except ImportError:
637 |         return {
638 |             "status": "active",
639 |             "info": "Orchestrator module not loaded",
640 |         }
641 | 
642 | 
643 | @app.get(
644 |     "/api/credentials/status",
645 |     response_model=CredentialStatus,
646 |     summary="Check whether required API keys are set",
647 | )
648 | def credentials_status() -> CredentialStatus:
649 |     """
650 |     Return a minimal view of credential readiness.
651 | 
652 |     Used by the frontend to gate runs and prompt users for missing keys.
653 |     """
654 |     return _credential_status()
655 | 
656 | 
657 | @app.post(
658 |     "/api/credentials",
659 |     response_model=CredentialStatus,
660 |     summary="Set Google/Modal credentials (persists to .env)",
661 | )
662 | def update_credentials(req: CredentialUpdateRequest) -> CredentialStatus:
663 |     """
664 |     Allow the UI to persist credentials locally.
665 | 
666 |     Keys are written to the running process and the .env file so subsequent
667 |     subprocesses inherit them.
668 |     """
669 |     try:
670 |         if req.google_api_key and req.google_api_key.strip():
671 |             _persist_env("GOOGLE_API_KEY", req.google_api_key.strip())
672 |         if req.anthropic_api_key and req.anthropic_api_key.strip():
673 |             _persist_env("ANTHROPIC_API_KEY", req.anthropic_api_key.strip())
674 |         if req.modal_token_id and req.modal_token_id.strip():
675 |             _persist_env("MODAL_TOKEN_ID", req.modal_token_id.strip())
676 |         if req.modal_token_secret and req.modal_token_secret.strip():
677 |             _persist_env("MODAL_TOKEN_SECRET", req.modal_token_secret.strip())
678 |     except Exception as e:
679 |         raise HTTPException(status_code=500, detail=f"Failed to persist credentials: {e}") from e
680 | 
681 |     return _credential_status()
682 | 
683 | 
684 | @app.post(
685 |     "/api/experiments/single",
686 |     response_model=ProcessSummary,
687 |     summary="Run a single-agent experiment (blocking)",
688 | )
689 | def run_single_experiment(req: SingleExperimentRequest) -> ProcessSummary:
690 |     """
691 |     Run the original single-agent researcher and wait for it to finish.
692 | 
693 |     This endpoint blocks until the underlying CLI command exits, then returns
694 |     a fully structured `ProcessSummary` containing all CLI output.
695 |     """
696 |     cmd = _build_single_command(req)
697 |     return _run_and_capture(
698 |         cmd,
699 |         mode="single",
700 |         task=req.task,
701 |         gpu=req.gpu,
702 |     )
703 | 
704 | 
705 | @app.post(
706 |     "/api/experiments/orchestrator",
707 |     response_model=ProcessSummary,
708 |     summary="Run the multi-agent orchestrator (blocking)",
709 | )
710 | def run_orchestrator_experiment(req: OrchestratorExperimentRequest) -> ProcessSummary:
711 |     """
712 |     Run the orchestrator mode end-to-end and wait for it to finish.
713 | 
714 |     The returned `ProcessSummary` includes all orchestrator logs, experiment
715 |     transcripts, and the final paper generated at the end of the run.
716 |     """
717 |     cmd = _build_orchestrator_command(req)
718 |     return _run_and_capture(
719 |         cmd,
720 |         mode="orchestrator",
721 |         task=req.task,
722 |         gpu=req.gpu,
723 |     )
724 | 
725 | 
726 | @app.post(
727 |     "/api/experiments/single/stream",
728 |     summary="Stream a single-agent experiment as newline-delimited JSON",
729 | )
730 | def stream_single_experiment(req: SingleExperimentRequest) -> StreamingResponse:
731 |     """
732 |     Run the single-agent researcher and stream all logs as NDJSON.
733 | 
734 |     This is ideal for front-ends that want to show real-time logs or
735 |     progressively render the final report as it is produced.
736 |     """
737 |     cmd = _build_single_command(req)
738 |     meta = {
739 |         "mode": "single",
740 |         "task": req.task,
741 |         "gpu": req.gpu,
742 |         "command": cmd,
743 |     }
744 |     return _stream_subprocess(cmd, meta=meta, credentials=req.credentials)
745 | 
746 | 
747 | @app.post(
748 |     "/api/experiments/orchestrator/stream",
749 |     summary="Stream the orchestrator as newline-delimited JSON",
750 | )
751 | def stream_orchestrator_experiment(
752 |     req: OrchestratorExperimentRequest,
753 | ) -> StreamingResponse:
754 |     """
755 |     Run the orchestrator mode and stream all logs as NDJSON.
756 | 
757 |     The stream includes orchestrator thinking, tool calls, and nested
758 |     single-agent transcripts exactly as printed by the CLI.
759 |     """
760 |     cmd = _build_orchestrator_command(req)
761 |     meta = {
762 |         "mode": "orchestrator",
763 |         "task": req.task,
764 |         "gpu": req.gpu,
765 |         "command": cmd,
766 |     }
767 |     return _stream_subprocess(cmd, meta=meta, credentials=req.credentials)
768 | 
769 | 
770 | @app.post(
771 |     "/api/agents/summarize",
772 |     response_model=AgentSummaryResponse,
773 |     summary="Summarize the last few sub-agent turns for the sidebar",
774 | )
775 | def summarize_agent(req: AgentSummaryRequest) -> AgentSummaryResponse:
776 |     """Run a cheap Gemini call that condenses recent agent thoughts/tool outputs."""
777 | 
778 |     try:
779 |         result = summarize_agent_findings(req.agent_id, [item.model_dump() for item in req.history])
780 |     except Exception as e:
781 |         raise HTTPException(status_code=500, detail=str(e)) from e
782 | 
783 |     return AgentSummaryResponse(**result)
784 | 
785 | 
786 | # ---------------------------------------------------------------------------
787 | # Static file serving for production (Railway, etc.)
788 | # ---------------------------------------------------------------------------
789 | # Mount static assets if the frontend dist folder exists
790 | if FRONTEND_DIST.exists() and (FRONTEND_DIST / "assets").exists():
791 |     app.mount("/assets", StaticFiles(directory=str(FRONTEND_DIST / "assets")), name="static-assets")
792 | 
793 | 
794 | @app.get("/{full_path:path}")
795 | async def serve_spa(full_path: str):
796 |     """
797 |     Catch-all route to serve the frontend SPA.
798 |     API routes are defined above, so they take precedence.
799 |     """
800 |     # If frontend dist exists, serve it
801 |     if FRONTEND_DIST.exists():
802 |         # Check if the requested file exists
803 |         file_path = FRONTEND_DIST / full_path
804 |         if file_path.exists() and file_path.is_file():
805 |             return FileResponse(file_path)
806 |         # Otherwise serve index.html for SPA routing
807 |         index_path = FRONTEND_DIST / "index.html"
808 |         if index_path.exists():
809 |             return FileResponse(index_path)
810 | 
811 |     # Fallback: return a simple message if no frontend
812 |     return {"message": "AI Researcher API is running. Frontend not built.", "docs": "/docs"}
813 | 
814 | 
815 | if __name__ == "__main__":
816 |     # Convenience entrypoint so you can run:
817 |     #   python api_server.py
818 |     # during development instead of calling uvicorn manually.
819 |     import uvicorn
820 | 
821 |     port = int(os.environ.get("PORT", 8000))
822 |     reload_enabled = os.environ.get("RAILWAY_ENVIRONMENT") is None  # Disable reload in production
823 | 
824 |     uvicorn.run(
825 |         "api_server:app",
826 |         host="0.0.0.0",
827 |         port=port,
828 |         reload=reload_enabled,
829 |     )
830 | 


--------------------------------------------------------------------------------