Lumo

https://github.com/starlightsearch/lumo
Admin
Lumo is a powerful autonomous agent framework written in Rust that leverages LLMs to solve complex...
Tokens:3,193
Snippets:14
Trust Score:6.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Lumo CLI Usage and Examples

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Documentation for the Lumo command-line interface, detailing available options for agent type, tools, model configuration, API keys, and providing usage examples for different LLM providers and tool configurations.

```APIDOC
lumo [OPTIONS]

Options:
  -a, --agent-type <TYPE>    Agent type. Options: function-calling, code, mcp [default: function-calling]
  -l, --tools <TOOLS>        Comma-separated list of tools. Options: google-search, duckduckgo, visit-website, python-interpreter [default: duckduckgo,visit-website]
  -m, --model-type <TYPE>    Model type. Options: openai, ollama, gemini [default: gemini]
  -k, --api-key <KEY>        LLM Provider API key
  --model-id <ID>            Model ID (e.g., "gpt-4" for OpenAI, "qwen2.5" for Ollama, or "gemini-2.0-flash" for Gemini) [default: gemini-2.0-flash]
  -b, --base-url <URL>       Base URL for the API
  --max-steps <N>            Maximum number of steps to take [default: 10]
  -p, --planning-interval <N> Planning interval
  -v, --logging-level <LEVEL> Logging level
  -h, --help                 Print help

Example commands:
# Using Gemini (default)
lumo -k your-gemini-key

# Using OpenAI with specific model
lumo -m openai --model-id gpt-4 -k your-openai-key

# Using Ollama with local model
lumo -m ollama --model-id qwen2.5 -b http://localhost:11434

# Using specific tools and agent type
lumo -a code -l duckduckgo,python-interpreter
```

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

### Lumo Server Configuration File Example

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Example YAML configuration for Lumo servers, defining commands, arguments, and environment variables for MCP agent usage. This file specifies how to run external services like exa-search.

```yaml
exa-search:
  command: npx
  args:
    - "exa-mcp-server"
  env: 
    EXA_API_KEY: "your-api-key"

fetch:
  command: uvx
  args:
    - "mcp_server_fetch"

system_prompt: |-
  You are a powerful agentic AI assistant...
```

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

### Start Lumo Server (Binary)

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Command to start the Lumo server application directly from its binary. The server defaults to listening on port 8080.

```bash
# Start the server (default port: 8080)
lumo-server
```

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

### Create .env File

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Copies the example .env file to create a new .env file in the lumo-server directory. This file is used to store sensitive configuration details like API keys.

```bash
cp lumo-server/.env.example lumo-server/.env
```

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

### Lumo Environment Variables for Configuration

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Lists the environment variables that can be used to configure Lumo, including API keys for various LLM providers and search tools. These variables allow for flexible setup without modifying command-line arguments.

```APIDOC
Environment Variables:

- OPENAI_API_KEY: Your OpenAI API key (optional, if using OpenAI model)
- GEMINI_API_KEY: Your Gemini API key (optional, if using Gemini model)
- SERPAPI_API_KEY: Google Search API key (optional, if using Google Search Tool)

Note: You can use models like Groq, TogetherAI using the same API as OpenAI by providing the base URL and API key.
```

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

### Run Pre-built Lumo Server Docker Image

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Instructions to pull a pre-built Lumo server Docker image from a registry and run it, mapping port 8080 and providing necessary API keys for various LLM providers.

```bash
# Pull the image
docker pull akshayballal95/lumo-server:latest

# Run with all required API keys
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your-openai-key \
  -e GOOGLE_API_KEY=your-google-key \
  -e GROQ_API_KEY=your-groq-key \
  -e ANTHROPIC_API_KEY=your-anthropic-key \
  -e EXA_API_KEY=your-exa-key \
  akshayballal95/lumo-server:latest
```

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

### Build and Run Lumo Server with Docker

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Instructions to build a Docker image for the Lumo server from a Dockerfile and then run the container, mapping port 8080 and setting essential API keys for LLM providers.

```bash
# Build the image
docker build -f server.Dockerfile -t lumo-server .

# Run the container with required API keys
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your-openai-key \
  -e GOOGLE_API_KEY=your-google-key \
  -e GROQ_API_KEY=your-groq-key \
  -e ANTHROPIC_API_KEY=your-anthropic-key \
  -e EXA_API_KEY=your-exa-key \
  lumo-server
```

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

### Build and Run Lumo from Source (Rust)

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Instructions for compiling and executing the Lumo agent directly from its Rust source code using Cargo. This involves building the release version and then running the executable. The agent can be run interactively.

```bash
cargo build --release
target/release/lumo
```

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

### Run Lumo Server with Tracing and API Keys

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Execute the Lumo server using Docker, exposing port 8080 and setting necessary environment variables for API keys (OpenAI, Google) and Langfuse tracing configuration.

```bash
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your-openai-key \
  -e GOOGLE_API_KEY=your-google-key \
  -e LANGFUSE_PUBLIC_KEY=your-langfuse-public-key \
  -e LANGFUSE_SECRET_KEY=your-langfuse-secret-key \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  lumo-server
```

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

### Configure Production Tracing

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Set environment variables for enabling OpenTelemetry tracing with Langfuse in a production environment. These variables configure the public key, secret key, and host for the tracing service.

```bash
LANGFUSE_PUBLIC_KEY=your-production-public-key
LANGFUSE_SECRET_KEY=your-production-secret-key
LANGFUSE_HOST=https://cloud.langfuse.com  # Or your production Langfuse instance URL
```

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

### Configure Development Tracing

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Set environment variables for enabling OpenTelemetry tracing with Langfuse in a development environment. These variables configure the public key, secret key, and host for the tracing service.

```bash
LANGFUSE_PUBLIC_KEY_DEV=your-dev-public-key
LANGFUSE_SECRET_KEY_DEV=your-dev-secret-key
LANGFUSE_HOST_DEV=http://localhost:3000  # Or your dev Langfuse instance URL
```

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

### Run Lumo using Docker

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Instructions for pulling and running the Lumo CLI image from Docker Hub. This method allows for easy deployment and execution, requiring the OpenAI API key to be passed as an environment variable.

```bash
# Pull the image
docker pull akshayballal95/lumo-cli:latest

# Run with your API key
docker run -it -e OPENAI_API_KEY=your-key-here lumo-cli
```

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

### Set API Keys in .env

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Sets various model API keys within the .env file for the Lumo server. These keys are essential for authenticating with external services like OpenAI, Google, Groq, Anthropic, and Exa.

```bash
OPENAI_API_KEY=your-openai-key
GOOGLE_API_KEY=your-google-key
GROQ_API_KEY=your-groq-key
ANTHROPIC_API_KEY=your-anthropic-key
EXA_API_KEY=your-exa-key
```

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

### Lumo Server API Endpoints

Source: https://github.com/starlightsearch/lumo/blob/main/README.md

Documentation for Lumo server's REST API endpoints, including health check and task execution. It details the HTTP methods, URLs, request headers, and request body parameters for running tasks.

```APIDOC
Health Check:
  GET /health_check
  Description: Checks if the Lumo server is running and responsive.
  Returns: Typically an empty response or a success status.

Run Task:
  POST /run
  Headers:
    Content-Type: application/json
  Request Body:
    {
      "task": "string" (required): The task to execute.
      "model": "string" (required): Model ID (e.g., "gpt-4", "qwen2.5", "gemini-2.0-flash").
      "base_url": "string" (required): Base URL for the API (e.g., "https://api.openai.com/v1/chat/completions").
      "tools": ["string"] (optional): Array of tool names to use (e.g., ["DuckDuckGo", "VisitWebsite"]).
      "max_steps": integer (optional): Maximum number of steps to take.
      "agent_type": "string" (optional): Type of agent to use ("function-calling" or "mcp").
      "history": [object] (optional): Array of previous messages for context.
    }
  Description: Executes a given task using the specified model and tools. The server automatically selects the correct API key based on the `base_url` provided.
  Example Request Body:
    {
      "task": "What is the weather in London?",
      "model": "gpt-4o-mini",
      "base_url": "https://api.openai.com/v1/chat/completions",
      "tools": ["DuckDuckGo", "VisitWebsite"],
      "max_steps": 5,
      "agent_type": "function-calling"
    }

API Key Detection:
  The server automatically detects the appropriate API key based on the `base_url`:
  - OpenAI URLs use `OPENAI_API_KEY`
  - Google URLs use `GOOGLE_API_KEY`
  - Groq URLs use `GROQ_API_KEY`
  - Anthropic URLs use `ANTHROPIC_API_KEY`
  - Exa URLs use `EXA_API_KEY`
```
Tokens:
Raw