Gego - GEO System for your brand, working with all LLMs

Gego is an open-source GEO (Generative Engine Optimization) tracker that schedules prompts across multiple Large Language Models (LLMs) and automatically extracts keywords from their responses. It helps you understand which keywords (brands, products, concepts) appear most frequently, which prompts generate the most mentions.

Features

• 🤖 Multi-LLM Support: Works with OpenAI, Anthropic, Ollama, Google, Perplexity, and custom LLM providers
• 📊 Hybrid Database: SQLite for configuration data (LLMs, Schedules) and MongoDB for analytics data (Prompts, Responses)
• ⏰ Flexible Scheduling: Cron-based scheduler for automated prompt execution
• 📈 Comprehensive Analytics: Track keyword mentions, compare prompts and LLMs, view trends
• 💻 User-Friendly CLI: Interactive commands for all operations
• 🔌 Pluggable Architecture: Easy to add new LLM providers and database backends
• 🎯 Automatic Keyword Extraction: Intelligently extracts keywords from responses (no predefined list needed)
• 📉 Performance Metrics: Monitor latency, token usage, and error rates
• 🔄 Retry Mechanism: Automatic retry with 30-second delays for failed requests
• 📝 Configurable Logging: DEBUG, INFO, WARNING, ERROR levels with file output support
• Personnas: create your own personnas for more accurate metrics

Use Cases

• SEO/Marketing Research: Track how brands and keywords are mentioned by AI assistants
• Competitive Analysis: Compare keyword visibility across different LLMs
• Prompt Engineering: Identify which prompts generate the most keyword mentions
• Trend Analysis: Monitor changes in keyword mentions over time

Installation

Prerequisites

• Go 1.21 or higher
• MongoDB (for analytics data)
• API keys for LLM providers (OpenAI, Anthropic, etc.)

Build from Source

git clone https://github.com/AI2HU/gego.git
cd gego
go build -o gego cmd/gego/main.go

Install via Go

# Install Gego directly from GitHub
go install github.com/AI2HU/gego/cmd/gego@latest

Docker Installation

Gego can be easily deployed using Docker with automatic database setup and migrations.

📘 For detailed deployment instructions, see DEPLOYMENT.md

Docker

# Build the Docker image
docker build -t gego:latest .

# Run with external MongoDB
docker run -d \
  --name gego \
  -p 8989:8989 \
  -e MONGODB_URI=mongodb://your-mongodb-host:27017 \
  gego:latest

Docker Environment Variables

• GEGO_CONFIG_PATH: Path to configuration file (default: /app/config/config.yaml)
• GEGO_DATA_PATH: Path to SQLite data directory (default: /app/data)
• GEGO_LOG_PATH: Path to log directory (default: /app/logs)

Docker Volumes

The Docker setup uses named volumes for persistent data:

• gego_data: SQLite database and configuration
• gego_config: Application configuration files
• gego_logs: Application logs
• mongodb_data: MongoDB data

Health Checks

Both containers include health checks:

• Gego: Checks API health endpoint every 30 seconds
• MongoDB: Checks database connectivity every 30 seconds

Stopping the Services

# Stop all services
docker-compose down

# Stop and remove volumes (WARNING: This will delete all data)
docker-compose down -v

Quick Start

1. Initialize Configuration

gego init

This interactive wizard will guide you through:

• Database configuration
• Connection testing

Note: Gego automatically extracts keywords from responses - no predefined keyword list needed!

2. Add LLM Providers

gego llm add

Example providers:

• OpenAI (GPT-4, GPT-3.5)
• Anthropic (Claude)
• Ollama (Local models)
• Google (Gemini)
• Perplexity (Sonar)

3. Create Prompts

gego prompt add

Example prompts:

• "What are the best streaming services for movies?"
• "Which cloud providers offer the best value?"
• "What are popular social media platforms?"

4. Set Up Schedules

gego schedule add

Create schedules to run prompts automatically using cron expressions.

5. Run Prompts

# Run all prompts with all LLMs once
gego run

# Start scheduler for scheduled execution
gego scheduler start

Run Command: Executes all enabled prompts with all enabled LLMs immediately.

Scheduler Commands: Manage scheduled execution of prompts.

6. Start API Server

# Start API server on default port 8989
gego api

# Start API server on custom port
gego api --port 3000

# Start API server on custom host and port
gego api --host 127.0.0.1 --port 5000

# Start API server with custom CORS origin
gego api --cors-origin "https://myapp.com"

# Start API server allowing all origins (default)
gego api --cors-origin "*"

API Server: Provides REST API endpoints for managing LLMs, prompts, schedules, and retrieving statistics.

Default Configuration:

• Host: 0.0.0.0 (all interfaces)
• Port: 8989
• CORS Origin: * (all origins allowed)
• Base URL: http://localhost:8989/api/v1

CORS Support:

• All HTTP Methods: GET, POST, PUT, DELETE, OPTIONS, PATCH, HEAD
• Headers: Content-Type, Authorization, X-Requested-With, Accept, Origin
• Credentials: Supported
• Preflight: Automatic OPTIONS handling

Available Endpoints:

• GET /api/v1/health - Health check
• GET /api/v1/llms - List all LLMs
• POST /api/v1/llms - Create new LLM
• GET /api/v1/llms/{id} - Get LLM by ID
• PUT /api/v1/llms/{id} - Update LLM
• DELETE /api/v1/llms/{id} - Delete LLM
• GET /api/v1/prompts - List all prompts
• POST /api/v1/prompts - Create new prompt
• GET /api/v1/prompts/{id} - Get prompt by ID
• PUT /api/v1/prompts/{id} - Update prompt
• DELETE /api/v1/prompts/{id} - Delete prompt
• GET /api/v1/schedules - List all schedules
• POST /api/v1/schedules - Create new schedule
• GET /api/v1/schedules/{id} - Get schedule by ID
• PUT /api/v1/schedules/{id} - Update schedule
• DELETE /api/v1/schedules/{id} - Delete schedule
• GET /api/v1/stats - Get statistics
• POST /api/v1/search - Search responses

Example API Usage:

# Health check
curl http://localhost:8989/api/v1/health

# List all LLMs
curl http://localhost:8989/api/v1/llms

# Create a new LLM
curl -X POST http://localhost:8989/api/v1/llms \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My GPT-4",
    "provider": "openai",
    "model": "gpt-4",
    "api_key": "sk-...",
    "enabled": true
  }'

# Get statistics
curl http://localhost:8989/api/v1/stats

Usage Examples

📘 For more detailed examples, see EXAMPLES.md

View Statistics

# Top keywords by mentions
gego stats keywords --limit 20

# Statistics for a specific keyword
gego stats keyword Dior

Manage LLMs

# List all LLMs
gego llm list

# Get LLM details
gego llm get <id>

# Enable/disable LLM
gego llm enable <id>
gego llm disable <id>

# Delete LLM
gego llm delete <id>

Manage Prompts

# List all prompts
gego prompt list

# Get prompt details
gego prompt get <id>

# Enable/disable prompt
gego prompt enable <id>
gego prompt disable <id>

# Delete prompt
gego prompt delete <id>

Manage Schedules

# List all schedules
gego schedule list

# Get schedule details
gego schedule get <id>

# Run schedule immediately
gego schedule run <id>

# Enable/disable schedule
gego schedule enable <id>
gego schedule disable <id>

# Delete schedule
gego schedule delete <id>

Manage Scheduler

# Check scheduler status
gego scheduler status

# Start scheduler (asks which schedule to start)
gego scheduler start

# Stop scheduler (asks which schedule to stop)
gego scheduler stop

# Restart scheduler (asks which schedule to restart)
gego scheduler restart

Interactive Schedule Selection: All scheduler commands will show available schedules and ask you to select which one to manage, or choose "all" for all schedules.

Configuration

Configuration is stored in ~/.gego/config.yaml:

sql:
  provider: sqlite
  uri: ~/.gego/gego.db

nosql:
  provider: mongodb
  uri: mongodb://localhost:27017
  database: gego

Database Architecture:

• SQLite: Stores LLM configurations and schedules (lightweight, local)
• MongoDB: Stores prompts and responses with analytics (scalable, indexed)

Note: Keywords are automatically extracted from LLM responses. No predefined list needed!

Keywords Exclusion

Gego automatically filters out common words that shouldn't be counted as keywords (like "The", "And", "AI", etc.). You can customize this exclusion list by creating a keywords_exclusion file in your Gego configuration directory (~/.gego/keywords_exclusion).

File Format:

• One word per line
• Lines starting with # are treated as comments
• Empty lines are ignored
• Case-sensitive matching (words must match exactly as they appear in the text)

Example keywords_exclusion file:

# Common articles and pronouns
The
A
An
And
Or

# Pronouns
I
You
He
She
It
We
They

# Common acronyms
AI
CRM
URL
API

# Add your own exclusions here
YourBrand
CommonWord

Location:

• Default: ~/.gego/keywords_exclusion
• Docker: /app/config/keywords_exclusion (if mounted)
• Custom: Same directory as your config.yaml file

Behavior:

• If the file doesn't exist, no words are excluded (all capitalized words are considered as keywords)
• The exclusion list is loaded once at startup and cached for performance
• Changes to the file require restarting the application to take effect

Logging

Gego includes a comprehensive logging system that allows you to control log levels an