LLM Setup

HypLab uses large language models (LLMs) to generate templates, create synthetic people, and build personas. This page shows you how to connect an AI provider.

HypLab supports multiple providers through LiteLLM:

• Google Gemini -- recommended for getting started
• OpenAI (GPT-4, GPT-3.5, etc.)
• Ollama -- run models locally, no API key needed
• Any OpenAI-compatible service (OpenRouter, Anthropic via proxy, etc.)

Option 1: Google Gemini

1. Get an API key from Google AI Studio
2. Add it to agents/.env:

LLM_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-key-here
GEMINI_MODEL=gemini-1.5-pro

3. Restart the agents.

Option 2: OpenAI

1. Get an API key from platform.openai.com
2. Add it to agents/.env:

LLM_PROVIDER=openai
LLM_API_KEY=sk-your-openai-key-here
LLM_MODEL=gpt-4

3. Restart the agents.

Option 3: Ollama (local, free)

Ollama lets you run models on your own machine. No API key or internet connection needed.

1. Install Ollama from ollama.com
2. Pull a model:

ollama pull llama2

3. Make sure Ollama is running:

ollama serve

4. Add to agents/.env:

LLM_PROVIDER=openai
LLM_API_KEY=ollama
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=llama2

5. Restart the agents.

Option 4: Any OpenAI-compatible service

Any service that exposes an OpenAI-compatible API works. Set LLM_BASE_URL to point at it:

LLM_PROVIDER=openai
LLM_API_KEY=your-key
LLM_BASE_URL=https://your-provider.com/v1
LLM_MODEL=model-name

Full configuration reference

OpenAI-compatible providers

Gemini

Config file alternative

Instead of environment variables, you can configure the LLM in agents/config.ini:

[LLM]
PROVIDER=openai
BASE_URL=https://api.openai.com/v1
MODEL=gpt-3.5-turbo
TEMPERATURE=0.7
MAX_TOKENS=8192
TIMEOUT=30

[Gemini]
MODEL=gemini-1.5-pro
TEMPERATURE=0.7
MAX_TOKENS=8192
TIMEOUT=30

Environment variables take precedence over config.ini.

Security reminders

• Never commit API keys to version control.
• For production deployments, use a secrets manager (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault). See the Deployment guides.
• Rotate API keys periodically.

What you should see

After configuring an LLM provider and restarting the agents, AI features should work. When you complete workspace onboarding, the system will generate templates using your configured provider instead of returning mock data.

If AI generation fails, check the agent logs and verify your API key is correct:

# Check agent logs (if running locally)
cd agents && make run-templates
# Look for connection errors or invalid key messages

Next: Core Concepts -- understand how HypLab is organized before you start using it.