1. Install

Option A: Local Installation

git clone https://github.com/Thysrael/Horizon.git
cd Horizon

# Install with uv (recommended)
uv sync

# Install test/development extras when needed
uv sync --extra dev

# Or with pip
pip install -e .

dev is currently defined as an optional extra in pyproject.toml, so use uv sync --extra dev for pytest and other development dependencies.

If you want the optional OpenBB financial-news source, install its extra too:

uv sync --extra openbb

If openbb pulls packages without wheels on your machine, install the SDK manually with binaries only:

uv pip install --only-binary=:all: openbb openbb-benzinga

Option B: Docker

git clone https://github.com/Thysrael/Horizon.git
cd Horizon

# Optional: build with comma-separated extras before the first run
docker compose build --build-arg EXTRAS=openbb horizon

Full-text extraction with trafilatura is included in the base install. The twitter extra also requires a Playwright browser and system packages, which the current Dockerfile does not install.

2. Configure

Option A: Interactive wizard (recommended)

uv run horizon-wizard

The wizard asks about your interests (e.g. "LLM inference", "嵌入式", "web security") and auto-generates data/config.json. See Interactive Wizard for CLI options.

Eligible ChatGPT subscribers can choose openai-chatgpt to use their plan through Sign in with ChatGPT, without an OpenAI API key.

Option B: Manual configuration

cp .env.example .env          # Add your API keys
cp data/config.example.json data/config.json  # Customize your sources

Minimal manual configuration:

{
  "ai": {
    "provider": "openai",
    "model": "gpt-4",
    "api_key_env": "OPENAI_API_KEY"
  },
  "sources": {
    "rss": [
      {
        "name": "Simon Willison",
        "url": "https://simonwillison.net/atom/everything/",
        "profile": "tech-news"
      }
    ]
  },
  "processing": {
    "profiles_dir": "profiles",
    "default_profile": "tech-news",
    "profile_settings": {
      "tech-news": {
        "threshold": 7.0,
        "topic_dedup": true
      }
    }
  }
}

An explicit source profile uses that profile directly. Omit it or set it to "auto" to let AI match the item against all available profiles. Set it to an array such as ["tech-news", "finance-news"] to restrict AI matching to those profiles. See Processing Profiles for profile structure and behavior. Per-profile user preferences such as score thresholds and topic deduplication belong in processing.profile_settings, not in the profile files.

Balanced digest (optional)

Limit the final digest size and prevent one category from dominating the results. Categories come from source configuration such as sources.rss[].category.

{
  "digest": {
    "max_items": 20,
    "category_groups": {
      "ai": {
        "limit": 5,
        "categories": ["ai-news", "ai-tools", "machine-learning"]
      },
      "finance": {
        "limit": 5,
        "categories": ["finance", "business", "equities"]
      }
    },
    "default_group": "other",
    "default_group_limit": 3
  }
}

Group limits are applied after profile filtering and before enrichment. If category_groups, max_items, and default_group_limit are omitted, no balanced digest limits apply.

api_key_env must be the name of an environment variable, not the API key itself. Put the real secret in .env:

OPENAI_API_KEY=sk-your-key

For Gemini, use GOOGLE_API_KEY:

{
  "ai": {
    "provider": "gemini",
    "model": "gemini-2.0-flash",
    "api_key_env": "GOOGLE_API_KEY"
  }
}

Any string value in data/config.json can reference environment variables with ${VAR_NAME}. This is useful for values such as ai.base_url, private RSS feed URLs, webhook endpoints, or custom header templates.

For the full reference, see the Configuration Guide.

3. Run

A. Local installation

uv run horizon [OPTIONS]

B. Docker

docker compose run --rm horizon [OPTIONS]

| Option | Default | Description | |--------|---------|-------------| | --hours N | 24 | Fetch from last N hours | | -d, --data-dir PATH | data | Path to the data directory | | -c, --config PATH | <data-dir>/config.json | Path to config file | | -l, --log-level LEVEL | WARNING | Logging level (DEBUG/INFO/WARNING/ERROR/CRITICAL) |

--data-dir changes the state directory, including summaries, subscribers, and the default config location; --config changes only the config file. The generated report is saved to data/summaries/ (or <data-dir>/summaries/ if --data-dir is set). See Configuration Paths for combining both flags and initializing a custom config location.

4. Auto

…