Skip to content

README.md

Latest commit

 

History

History
190 lines (151 loc) · 6.41 KB

README.md

File metadata and controls

190 lines (151 loc) · 6.41 KB

Holosophos

Autonomous research assistant composed of specialized agents for literature discovery, experiment execution on remote GPUs, technical writing, idea generation, and paper review.

Built on top of:

Features

  • Manager agent: Orchestrates task flow across specialized agents.
  • Librarian: Searches papers (ArXiv, ACL Anthology, Semantic Scholar), reads webpages, and analyzes documents.
  • MLE Solver: Writes and runs code on remote GPUs via MLE Kit MCP tools.
  • Writer: Composes LaTeX reports/papers and compiles them to PDF.
  • Proposer: Generates and scores research ideas given context and a baseline paper.
  • Reviewer: Reviews papers with venue-grade criteria.

Architecture at a glance

  • Server entrypoint: holosophos.server (starts a CodeArkt server with the composed agent team)
  • Agent composition: holosophos.main_agent.compose_main_agent
  • Agent prompts: holosophos/prompts/*.yaml
  • Settings: holosophos/settings.py (env-driven via pydantic-settings)
  • External MCPs:
    • academia_mcp (papers/search)
    • mle_kit_mcp (remote GPU execution, file ops)
  • Optional tracing/observability: Phoenix (OTLP)

Requirements

  • Python 3.12+
  • Docker
  • uv (recommended for fast Python environment management)

Installation

uv venv .venv
source .venv/bin/activate
make install

Environment configuration

Create a .env file at the project root. Typical entries:

# LLM provider keys (use what you need)
OPENROUTER_API_KEY=...

# Tooling keys
TAVILY_API_KEY=...
VAST_AI_KEY=...

# Optional observability
PHOENIX_URL=http://localhost:6006
PHOENIX_PROJECT_NAME=holosophos

# MCP endpoints when running locally
ACADEMIA_MCP_URL=http://0.0.0.0:5056/mcp
MLE_KIT_MCP_URL=http://0.0.0.0:5057/mcp

# App options
MODEL_NAME=deepseek/deepseek-chat-v3.1
PORT=5055

Holosophos reads configuration from holosophos/settings.py. You can override any setting via environment variables (case-insensitive), for example MODEL_NAME, MAX_COMPLETION_TOKENS, ENABLE_PHOENIX=true, or custom PHOENIX_ENDPOINT.

Quickstart: Local (multi-process)

Open separate terminals and run:

  1. Phoenix (optional, for traces)
docker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix
  1. Academia MCP (papers)
uv run python -m academia_mcp --port 5056
  1. MLE Kit MCP (GPU exec; with local workspace bind)
uv run python -m mle_kit_mcp --port 5057 --workspace workdir
  1. Holosophos server
uv run python -m holosophos.server --port 5055 --enable-phoenix
  1. Client UI (choose one)
# Gradio UI
uv run python -m codearkt.gradio

# Terminal client
uv run python -m codearkt.terminal

The server listens on http://localhost:5055. The manager agent will call into MCP tools from Academia and MLE Kit as needed.

Quickstart: Docker Compose

Holosophos ships with a docker-compose.yml that brings up:

  • app (Holosophos server)
  • executor (CodeArkt executor)
  • phoenix (optional tracing UI and OTLP collector)
  • academia (Academia MCP)
  • mle_kit (MLE Kit MCP, with ./workdir mounted and Docker socket pass-through)

Steps:

# 1) Ensure you have a .env at project root (see above)
# 2) Start the stack
docker compose up --build

Default ports:

  • App: http://localhost:5055
  • Phoenix UI: http://localhost:6006
  • Academia MCP: http://localhost:5056
  • MLE Kit MCP: http://localhost:5057

You can change ports via environment variables in docker-compose.yml (APP_PORT, PHOENIX_UI_PORT, PHOENIX_OTLP_PORT, ACADEMIA_PORT, MLE_KIT_PORT).

Compose commands and tips

# Start everything in the background
docker compose up -d --build

# Tail logs for a service
docker compose logs -f app
docker compose logs -f phoenix
docker compose logs -f academia
docker compose logs -f mle_kit
docker compose logs -f executor

# Restart or rebuild a single service
docker compose restart app
docker compose build app --no-cache && docker compose up -d app

# Stop and remove (including named volumes, if any)
docker compose down -v

Override ports and options at runtime

# Example: change app and Phoenix UI ports for this run only
APP_PORT=8055 PHOENIX_UI_PORT=6606 docker compose up -d --build

Workspace and persistence

  • ./workdir is bind-mounted into both academia and mle_kit containers at /workdir.
  • Use workdir/ for inputs and outputs you want to inspect or edit from the host.
  • The mle_kit service has /var/run/docker.sock mounted to orchestrate jobs; see the security note below.

Interacting with the stack

Run a client in a separate terminal to talk to the app at http://localhost:${APP_PORT:-5055}:

# Gradio UI
uv run python -m codearkt.gradio

# or terminal client
uv run python -m codearkt.terminal

Customizing the model and tracing

  • Set MODEL_NAME in .env (or export it) to change the model (default comes from holosophos/settings.py).
  • Enable tracing by setting ENABLE_PHOENIX=true and ensuring Phoenix is up. The app will send OTLP traces to ${PHOENIX_URL}/v1/traces unless PHOENIX_ENDPOINT is provided.

Security note

Mounting /var/run/docker.sock into mle_kit grants it control over the host Docker daemon. Only run this stack on a trusted machine and network.

Using the agents

The server composes a manager agent with five specialists:

  • librarian: queries literature and the web (no file system access)
  • mle_solver: executes code on remote GPUs (remote tools)
  • writer: creates LaTeX PDFs (templates, compile)
  • proposer: ideates and scores research proposals
  • reviewer: reviews papers using venue-style rubrics

Prompts live under holosophos/prompts/ and can be customized per agent (*.yaml). Tool sets and iteration limits are configured in holosophos/settings.py and can be overridden via environment variables.

Development

  • Install dev tools: make install
  • Format: make black
  • Lint & type-check: make validate
  • Tests: make test

Troubleshooting

  • If the manager cannot reach MCP servers, verify ACADEMIA_MCP_URL and MLE_KIT_MCP_URL match the ports you started.
  • For tracing, ensure Phoenix is running and ENABLE_PHOENIX=true (or pass --enable-phoenix).
  • Ensure LLM credentials are present in .env for your chosen provider(s).