K-Dense BYOK Co-Scientist

K-Dense Ecosystem
├── Claude Scientific Skills  (170+ skills, open-source)
│     ├── Genomics, proteomics, cell biology
│     ├── Chemistry, drug discovery, materials science
│     ├── Physics, astrophysics, engineering
│     ├── Finance, social science, mathematics
│     └── ML, data science, clinical
├── K-Dense BYOK              (open-source desktop app) ← this system
│     ├── Kady agent (orchestrator)
│     ├── Expert sub-agents (Gemini CLI + skills)
│     ├── 326 workflow templates
│     └── MCP server extensibility
└── K-Dense Web                (commercial SaaS platform)
      ├── Managed infrastructure
      ├── Team collaboration
      └── No-setup deployment

{
  "id": "unique-kebab-case-id",
  "name": "Human-Readable Name",
  "description": "One-sentence summary shown on the card",
  "category": "genomics",
  "icon": "Dna",
  "prompt": "Detailed instructions with {placeholder} syntax",
  "suggestedSkills": ["scanpy", "scientific-visualization"],
  "placeholders": [
    { "key": "placeholder", "label": "User prompt", "required": true }
  ],
  "requiresFiles": true
}

┌─────────────────────────────────────────────────────┐
│                    User Interface                     │
│                   (port 3000)                         │
└───────────────────────┬─────────────────────────────┘
                        │ chat message
                        ▼
┌─────────────────────────────────────────────────────┐
│              Kady (Orchestrator Agent)                │
│          Model: User-selected (40+ options)           │
│          Provider: OpenRouter → LiteLLM proxy         │
│                                                       │
│   Capabilities:                                       │
│   • Direct Q&A for simple questions                   │
│   • Task classification and routing                   │
│   • Expert delegation decisions                       │
│   • Web search via Parallel API                       │
│   • File operations in sandbox                        │
└───────────────────────┬─────────────────────────────┘
                        │ delegation
                        ▼
┌─────────────────────────────────────────────────────┐
│              Expert Sub-Agents                        │
│          Model: Gemini (always, via Gemini CLI)       │
│          Provider: OpenRouter                         │
│                                                       │
│   Capabilities:                                       │
│   • 170+ scientific skill execution                   │
│   • Code generation and execution                     │
│   • Scientific database queries                       │
│   • File creation and manipulation                    │
│   • MCP server tool invocation                        │
└─────────────────────────────────────────────────────┘

# 1. Clone
git clone https://github.com/K-Dense-AI/k-dense-byok.git
cd k-dense-byok

# 2. Configure (minimum: OpenRouter API key)
cp kady_agent/env.example kady_agent/.env
# Edit .env, add OPENROUTER_API_KEY

# 3. Start (auto-installs dependencies on first run)
chmod +x start.sh
./start.sh
# → Frontend on :3000, Backend on :8000, LiteLLM on :4000

sandbox/
├── [uploaded files]
├── [generated files]
├── [expert task outputs]
└── [intermediate results]

Cost = Kady_tokens × OpenRouter_rate(selected_model)
     + Expert_tokens × OpenRouter_rate(Gemini_model)
     + Parallel_API_calls × Parallel_rate           [if web search enabled]
     + Modal_compute × Modal_rate                    [if remote compute enabled]

┌─────────────────────────────────────────────────────────────────────┐
│                         User's Computer                              │
│                                                                      │
│  ┌──────────────┐   ┌────────────────────┐   ┌──────────────────┐   │
│  │   Frontend    │   │     Backend        │   │  LiteLLM Proxy   │   │
│  │   (Next.js)   │◄─►│  (Python/FastAPI)  │──►│   (port 4000)    │   │
│  │   port 3000   │   │    port 8000       │   │                  │   │
│  │               │   │                    │   │  Translates to   │   │
│  │  • Chat UI    │   │  • Kady agent      │   │  OpenRouter API  │   │
│  │  • File mgr   │   │  • Expert dispatch │   │                  │   │
│  │  • Workflows  │   │  • Tool execution  │   │  40+ models      │   │
│  │  • Preview    │   │  • File I/O        │   │  accessible      │   │
│  └──────────────┘   └────────┬───────────┘   └────────┬─────────┘   │
│                              │                         │              │
│                    ┌─────────▼──────────┐              │              │
│                    │     Sandbox        │              │              │
│                    │   (local files)    │              │              │
│                    │                    │              │              │
│                    │  Uploaded files,   │              │              │
│                    │  generated output  │              │              │
│                    └───────────────────┘              │              │
│                                                       │              │
└───────────────────────────────────────────────────────┼──────────────┘
                                                        │
                            ┌───────────────────────────▼──────────┐
                            │          External Services            │
                            │                                       │
                            │  • OpenRouter (LLM API gateway)       │
                            │  • Parallel (web search)              │
                            │  • Modal (remote compute)             │
                            │  • 250+ scientific databases          │
                            │  • Custom MCP servers                 │
                            └───────────────────────────────────────┘

User Message
    │
    ▼
┌─────────────────────────────────┐
│          Kady (Orchestrator)     │
│  Model: user-selected via       │
│         OpenRouter               │
│                                  │
│  Decision tree:                  │
│  ├── Simple Q&A → answer direct  │
│  ├── Web needed → Parallel API   │
│  ├── File op → sandbox tools     │
│  └── Expert needed → delegate    │
└──────────────┬──────────────────┘
               │ delegation (complex tasks)
               ▼
┌─────────────────────────────────┐
│      Expert Sub-Agent            │
│  Model: Gemini (always)          │
│  Runtime: Gemini CLI             │
│                                  │
│  Injected context:               │
│  ├── Scientific skills (170+)    │
│  ├── MCP server tools            │
│  ├── Database API keys           │
│  └── Sandbox file access         │
│                                  │
│  Output:                         │
│  ├── Text responses              │
│  ├── Generated files             │
│  ├── Visualizations              │
│  └── Code + execution results    │
└─────────────────────────────────┘

1. User types message in browser UI (port 3000)
2. Frontend sends HTTP request to backend (port 8000)
3. Backend's Kady agent processes the message:
   a. If simple → route through LiteLLM proxy (port 4000) → OpenRouter → selected model
   b. If complex → spawn expert sub-agent via Gemini CLI
4. Expert agent:
   a. Receives task + relevant skills + tool definitions
   b. Executes via Gemini CLI (always Gemini model via OpenRouter)
   c. May call tools: web search, database APIs, code execution, file I/O
   d. Returns results to Kady
5. Kady synthesizes and streams response back to frontend
6. Generated files appear in sandbox/ and are visible in file browser

k-dense-byok/
├── start.sh              ← One-command startup (installs deps, launches services)
├── server.py             ← Python backend server (FastAPI-based, port 8000)
│
├── kady_agent/           ← Core agent logic
│   ├── agent.py          ← Main Kady agent definition and routing logic
│   ├── env.example       ← Template for API keys (50+ configurable keys)
│   ├── .env              ← User's actual API keys (gitignored)
│   └── tools/            ← Tool definitions for Kady
│       ├── web_search.py       ← Parallel API integration
│       ├── delegate.py         ← Expert delegation logic
│       ├── file_ops.py         ← Sandbox file operations
│       └── [other tools]       ← MCP, database connectors, etc.
│
├── web/                  ← Frontend application
│   ├── src/
│   │   ├── components/         ← React components
│   │   │   ├── chat/           ← Chat interface
│   │   │   ├── file-browser/   ← File management sidebar
│   │   │   ├── preview/        ← File preview panel
│   │   │   └── workflows/      ← Workflow template browser
│   │   ├── data/
│   │   │   └── workflows.json  ← 326 workflow definitions
│   │   └── [app infrastructure]
│   └── package.json
│
├── sandbox/              ← Isolated file workspace (created at runtime)
│
└── user_config/          ← Persistent user settings
    └── custom_mcps.json  ← Custom MCP server configurations

                    start.sh
                   /    |    \
                  /     |     \
           Frontend  Backend  LiteLLM
           (web/)   (server.py) (proxy)
              │         │         │
              │    kady_agent/    │
              │    ├── agent.py   │
              │    └── tools/     │
              │         │         │
              │    Gemini CLI ────┘
              │    (expert execution)
              │         │
              │    Scientific Skills
              │    (170+ .md files)
              │         │
              └────► sandbox/
                   (file I/O)

Input: User message M

1. CLASSIFY(M):
   ├── SIMPLE_QA      → Generate direct response using selected model
   ├── WEB_REQUIRED   → Invoke Parallel API search, then synthesize
   ├── FILE_OPERATION  → Execute sandbox file tool, return result
   └── EXPERT_NEEDED   → Invoke expert delegation pipeline

2. If EXPERT_NEEDED:
   a. Extract task description T from M
   b. Identify relevant domain D from context
   c. Select skills S = skill_selector(D, T) from 170+ available
   d. Spawn expert sub-agent with (T, S, tools, sandbox_access)
   e. Stream expert output back to user
   f. Synthesize final response incorporating expert results

3. POST-PROCESS:
   ├── If files generated → update file browser sidebar
   ├── If code executed → display execution results
   └── If error occurred → retry or explain failure

Expert Delegation Pipeline
│
├── 1. Task Packaging
│   ├── Extract task description from conversation
│   ├── Select suggested skills from workflow (if applicable)
│   ├── Inject relevant API keys from .env
│   └── Configure sandbox file access paths
│
├── 2. Gemini CLI Invocation
│   ├── Spawn Gemini CLI process
│   ├── Pass task + skills as system context
│   ├── Register available tools:
│   │   ├── Built-in: code execution, file I/O
│   │   ├── Scientific: database APIs, computation
│   │   └── Custom: MCP server tools
│   └── Model: Gemini (via OpenRouter, always)
│
├── 3. Execution Loop
│   ├── Gemini agent reasons about task
│   ├── Calls tools as needed (multi-turn)
│   ├── Generates intermediate files in sandbox
│   ├── Streams progress back to backend
│   └── Returns final result to Kady
│
└── 4. Result Integration
    ├── Kady receives expert output
    ├── Synthesizes user-facing response
    ├── Updates file browser with new files
    └── Streams to frontend

Skill Structure (Markdown)
│
├── Metadata
│   ├── Skill name and ID
│   ├── Domain tags (e.g., genomics, chemistry)
│   ├── Required tools (e.g., python, database API)
│   └── Suggested packages (e.g., scanpy, rdkit)
│
├── Instructions
│   ├── Step-by-step procedure for domain task
│   ├── Best practices and common pitfalls
│   ├── Expected input/output formats
│   └── Error handling guidance
│
└── Examples
    ├── Sample inputs and expected outputs
    ├── Code snippets for reference
    └── Interpretation guidelines

Life Sciences          Physical Sciences      Formal Sciences
├── genomics           ├── physics            ├── math
├── proteomics         ├── astrophysics       └── ml
├── cellbio            ├── engineering
├── ecology            └── materials          Research Ops
└── clinical                                  ├── paper
                       Chemical Sciences      ├── literature
Health Sciences        ├── chemistry          ├── data
├── clinical           └── drugdiscovery      ├── grants
└── neuro                                     ├── scicomm
                       Social Sciences        └── visual
                       ├── finance
                       └── social

Workflow Execution Flow
│
├── 1. User browses workflow library
│   └── Grouped by 22 categories with Lucide icons
│
├── 2. User selects workflow and fills placeholders
│   ├── Required fields validated
│   ├── Optional file uploads attached
│   └── Model selection (for Kady) confirmed
│
├── 3. Prompt assembly
│   ├── Template prompt with {placeholders} filled
│   ├── suggestedSkills attached as metadata
│   ├── requiresFiles flag checked
│   └── Full prompt sent to Kady
│
├── 4. Kady processes assembled prompt
│   ├── Typically delegates to expert (workflow complexity)
│   ├── Expert receives skills suggested by workflow
│   └── Execution follows workflow steps
│
└── 5. Results
    ├── Generated files in sandbox
    ├── Streamed text response
    └── File preview in UI

{
  "built-in-servers": {
    "docling": { "command": "...", "args": ["..."] },
    "parallel-search": { "command": "...", "args": ["..."] }
  },
  "custom-servers (user-defined)": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    },
    "remote-api": {
      "httpUrl": "https://mcp.example.com/api",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

Local Expert Agent
    │
    ├── Lightweight tasks → local Python execution
    │
    └── Heavy tasks → Modal API
        ├── GPU-accelerated computation
        ├── Large dataset processing
        ├── Model training/inference
        └── Resource-intensive simulations

Session Memory Model
│
├── Conversation History (in-memory)
│   ├── User messages
│   ├── Kady responses
│   ├── Tool call results
│   └── Expert delegation outputs
│
├── Sandbox Persistence (filesystem)
│   ├── Uploaded files persist across messages
│   ├── Generated files accumulate during session
│   └── Files survive app restarts (in sandbox/)
│
└── Configuration Persistence (filesystem)
    ├── API keys in .env (permanent)
    ├── Custom MCP servers in user_config/ (permanent)
    └── No cross-session conversation memory

Session N                          Session N+1
│                                  │
├── User interactions              ├── Fresh start
├── Expert delegations             ├── No memory of Session N
├── Generated outputs              ├── Same skill library
└── Session ends → no extraction   └── Same workflows