Trending-skills k-dense-byok-ai-scientist

---
name: k-dense-byok-ai-scientist
description: AI co-scientist desktop app with Claude Scientific Skills, multi-model support, and 250+ scientific databases via BYOK API keys
triggers:
  - set up K-Dense BYOK
  - configure Kady AI assistant
  - add scientific skills to my project
  - integrate K-Dense with my research workflow
  - use K-Dense BYOK with my API keys
  - run AI co-scientist locally
  - connect OpenRouter to K-Dense
  - add web search to Kady agent
---

# K-Dense BYOK AI Co-Scientist

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

K-Dense BYOK is an open-source desktop AI research assistant ("Kady") that runs locally, uses your own API keys (BYOK), and gives you access to 170+ scientific skills, 250+ scientific databases, and 500k+ Python packages. It supports 40+ AI models via OpenRouter and optionally delegates heavy compute to Modal cloud infrastructure.

## Architecture

Three services run together on your machine:

| Service | Port | Role |
|---------|------|------|
| Frontend (Next.js) | 3000 | Chat UI, file browser, file preview |
| Backend (FastAPI) | 8000 | Kady agent, expert coordination, tools |
| LiteLLM proxy | 4000 | Routes AI requests to OpenRouter models |

Expert/coding tasks always use Gemini CLI via OpenRouter regardless of the model selected in the UI dropdown.

## Prerequisites

- macOS, Linux, or Windows (via WSL)
- Git
- An OpenRouter API key — [openrouter.ai](https://openrouter.ai/)
- *(Optional)* Parallel API key for web search — [parallel.ai](https://parallel.ai/)
- *(Optional)* Modal credentials for remote compute — [modal.com](https://modal.com/)

## Installation

```bash
git clone https://github.com/K-Dense-AI/k-dense-byok.git
cd k-dense-byok

Configuration

Create

kady_agent/.env

:

# Required
OPENROUTER_API_KEY=$OPENROUTER_API_KEY

# Optional — enables web search
PARALLEL_API_KEY=$PARALLEL_API_KEY

# Internal service wiring — leave as-is
GOOGLE_GEMINI_BASE_URL=http://localhost:4000
GEMINI_API_KEY=sk-litellm-local

# Default model for Kady (changeable in UI dropdown)
DEFAULT_AGENT_MODEL=openrouter/google/gemini-3.1-pro-preview

# Optional — Modal remote compute
MODAL_TOKEN_ID=$MODAL_TOKEN_ID
MODAL_TOKEN_SECRET=$MODAL_TOKEN_SECRET

Starting the App

chmod +x start.sh
./start.sh

On first run,

start.sh

automatically installs:

• Python packages and dependencies
• Node.js packages
• Gemini CLI
• Scientific skills

App opens at http://localhost:3000. Stop with

Ctrl+C

.

Project Structure

k-dense-byok/
├── start.sh              # One-command launcher
├── server.py             # FastAPI backend
├── kady_agent/
│   ├── .env              # API keys
│   ├── agent.py          # Main Kady agent definition
│   └── tools/            # Web search, delegation, file ops
├── web/                  # Next.js frontend
└── sandbox/              # Local file workspace (auto-created)

Key Files to Understand

kady_agent/agent.py

— Main Agent

This defines Kady's behavior, system prompt, and tool access. Modify this to change how Kady responds, which tools it uses, or to add custom instructions.

# kady_agent/agent.py (illustrative structure)
from anthropic import Anthropic

client = Anthropic()

# Kady decides: answer directly OR delegate to an expert
# Experts have access to 170+ scientific skills

kady_agent/tools/

— Tool Definitions

Each file in

tools/

adds a capability to Kady:

• Web search (via Parallel API)
• Expert delegation (fires up a Gemini CLI subprocess)
• File read/write in the sandbox
• Scientific database queries

Adding a Custom Tool (TypeScript/Backend Pattern)

If extending the backend with a new tool:

// web/src/lib/api.ts — example frontend API call pattern
const response = await fetch('http://localhost:8000/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: userMessage,
    session_id: sessionId,
    model: selectedModel,       // e.g. "openrouter/anthropic/claude-opus-4-5"
    files: attachedFiles,
  }),
});

const reader = response.body?.getReader();
// Streams back tokens as SSE

// web/src/components/Chat.tsx — reading streamed response
async function streamResponse(reader: ReadableStreamDefaultReader) {
  const decoder = new TextDecoder();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const chunk = decoder.decode(value);
    appendToMessage(chunk);
  }
}

Selecting AI Models

The UI dropdown supports 40+ models. You can also set the default in

.env

:

# Examples of valid DEFAULT_AGENT_MODEL values
DEFAULT_AGENT_MODEL=openrouter/google/gemini-3.1-pro-preview
DEFAULT_AGENT_MODEL=openrouter/anthropic/claude-opus-4-5
DEFAULT_AGENT_MODEL=openrouter/openai/gpt-4o
DEFAULT_AGENT_MODEL=openrouter/x-ai/grok-3
DEFAULT_AGENT_MODEL=openrouter/qwen/qwen-2.5-72b-instruct

Note: The dropdown model only controls Kady. Expert/coding delegation always uses a Gemini model via OpenRouter.

Working with Files

Files go in and come from the

sandbox/

directory. Users can:

• Upload files via the UI
• Ask Kady to create/modify files
• Preview almost any file type in the side panel

# Backend file tool pattern (server.py / tools)
import os

SANDBOX_DIR = os.path.join(os.path.dirname(__file__), "sandbox")

def read_file(filename: str) -> str:
    path = os.path.join(SANDBOX_DIR, filename)
    with open(path, "r") as f:
        return f.read()

def write_file(filename: str, content: str) -> None:
    path = os.path.join(SANDBOX_DIR, filename)
    os.makedirs(os.path.dirname(path), exist_ok=True)
    with open(path, "w") as f:
        f.write(content)

Enabling Web Search

Set

PARALLEL_API_KEY

in

kady_agent/.env

. Kady will automatically use web search when it determines live information is needed — no code changes required.

Enabling Remote Compute (Modal)

MODAL_TOKEN_ID=$MODAL_TOKEN_ID
MODAL_TOKEN_SECRET=$MODAL_TOKEN_SECRET

Once set, Kady's experts can offload heavy computation (large dataset processing, ML training, etc.) to Modal cloud hardware instead of running locally.

MCP (Model Context Protocol) Configuration

MCP can be configured directly in the code today. UI-based MCP config is on the roadmap. To add an MCP server manually, locate the agent configuration in

kady_agent/agent.py

and add your MCP server definition there.

Common Patterns

Ask Kady to use a specific scientific skill

"Analyze this genomics dataset using bioinformatics tools"
"Run a financial time-series analysis on this CSV"
"Search PubMed for recent papers on CRISPR delivery mechanisms"

Ask Kady to search + synthesize

"Search the web for the latest benchmarks on protein folding models and summarize the findings"

Ask Kady to write and run code

"Write a Python script to parse this FASTA file and plot GC content, then run it"

File workflow

"I've uploaded data.csv — clean it, run a regression, and save the results as results.csv"

Troubleshooting

App won't start / port already in use

# Kill processes on ports 3000, 4000, 8000
lsof -ti:3000,4000,8000 | xargs kill -9
./start.sh

OPENROUTER_API_KEY

not found error

• Confirm

  kady_agent/.env

  exists (not

  .env

  in the root)
• Check for typos — no quotes needed around values

Gemini CLI / expert tasks failing

• Expert tasks always route through OpenRouter using a Gemini model
• Verify your OpenRouter account has credits and Gemini model access
• Check

  GOOGLE_GEMINI_BASE_URL=http://localhost:4000

  and

  GEMINI_API_KEY=sk-litellm-local

  are unchanged

Scientific skills not downloading

• First run requires internet access; subsequent runs are cached
• Re-run

  ./start.sh

  — it will retry failed downloads

Web search not working

• Confirm

  PARALLEL_API_KEY

  is set in

  kady_agent/.env

• Verify the key is active at parallel.ai

Slow first startup

• Normal —

  start.sh

  installs Python packages, Node modules, Gemini CLI, and downloads skills
• Subsequent starts are significantly faster

Windows / WSL issues

• Run everything inside WSL, not PowerShell/CMD
• File paths must use Linux-style

  /

  separators inside WSL

Staying Updated

git pull origin main
./start.sh   # picks up any new dependencies automatically

Star the repo and follow @k_dense_ai for release notes. Planned additions include Ollama local model support, Claude Code as delegation backend, AutoResearch integration, and improved PDF parsing.