HelixAgentAi 0.1.3__tar.gz

helixagentai-0.1.3/.env.example

@@ -0,0 +1,117 @@
+# Helix environment — copy to ~/.helix/.env (primary location)
+# Optional: ./.env in a project dir (lower priority than ~/.helix/.env)
+
+# --- Environment ---
+HELIX_ENV=development
+# HELIX_HOME=   # override data dir (default: ~/.helix, XDG_DATA_HOME/helix, or %LOCALAPPDATA%\Helix on Windows)
+# production: forces auth, stricter Telegram/CORS checks
+
+# --- LLM (legacy single-provider; prefer helix models setup + profile providers) ---
+MODEL=qwen2.5-coder:32b
+BASE_URL=http://localhost:11434/v1
+API_KEY=ollama
+TEMPERATURE=0.7
+
+# --- Cloud provider API keys (used via ${ENV:VAR} in ~/.helix/profiles/*/config.yaml) ---
+# OPENAI_API_KEY=
+# OPENROUTER_API_KEY=
+# OPENROUTER_HTTP_REFERER=https://github.com/your-org/helix
+# DEEPSEEK_API_KEY=
+# MOONSHOT_API_KEY=
+# XAI_API_KEY=
+# GROQ_API_KEY=
+# GOOGLE_API_KEY=
+# MISTRAL_API_KEY=
+# TOGETHER_API_KEY=
+# FIREWORKS_API_KEY=
+# CEREBRAS_API_KEY=
+# LITELLM_API_KEY=
+# Hosts for local / remote inference (used by helix models add ollama|litellm|vllm)
+# OLLAMA_HOST=http://127.0.0.1:11434
+# LITELLM_API_BASE=http://127.0.0.1:4000
+# VLLM_HOST=http://127.0.0.1:8000
+
+# --- Agent ---
+MAX_STEPS=15
+DATA_DIR=data
+
+# --- Logging (helix logs) ---
+# HELIX_LOG_LEVEL=INFO
+# HELIX_LOG_DEBUG=false
+# HELIX_LOG_MAX_BYTES=10485760
+# HELIX_LOG_BACKUP_COUNT=10
+# HELIX_LOG_ROTATION_DAYS=14
+
+# --- Web TUI (helix tui --web) ---
+# HELIX_TUI_WEB_TOKEN=   # required for --allow-lan / production; optional on 127.0.0.1
+
+# --- Gateway ---
+HELIX_GATEWAY_HOST=127.0.0.1
+HELIX_GATEWAY_PORT=8000
+# HELIX_GATEWAY_WITH_DOCS=1
+# HELIX_DOCS_HOST=127.0.0.1
+# HELIX_DOCS_PORT=8080
+HELIX_REQUIRE_AUTH=false
+HELIX_CORS_ORIGINS=http://127.0.0.1:8000,http://localhost:8000
+HELIX_API_KEYS_DB=data/security/api_keys.db
+HELIX_API_KEY_PEPPER=
+HELIX_RATE_LIMIT_RPM=100
+HELIX_ADMIN_RATE_LIMIT_RPM=30
+HELIX_ENABLE_PROMETHEUS_METRICS=true
+
+# --- Tools (production: disable risky tools) ---
+HELIX_ENABLE_CODE_EXECUTOR=true
+HELIX_ENABLE_TERMINAL_TOOL=true
+HELIX_TERMINAL_COMMAND_WHITELIST=true
+# Extra allowed commands/prefixes (comma-separated): helix gateway start, docker, make
+# HELIX_TERMINAL_WHITELIST_EXTRA=helix,uv,docker,make
+
+# --- Telegram (optional: uv sync --extra telegram) ---
+TELEGRAM_BOT_TOKEN=
+HELIX_TELEGRAM_ALLOWED_USERS=
+# HELIX_TELEGRAM_ALLOW_ALL=true  # dev only: allow any Telegram user (never use in production)
+HELIX_TELEGRAM_PROFILE=default
+
+# --- Voice Messages (Telegram) ---
+# Вариант A — OpenAI Whisper напрямую:
+# OPENAI_API_KEY=sk-...
+# HELIX_WHISPER_MODEL=whisper-1
+#
+# Вариант B — через LiteLLM proxy (нужна модель whisper в config LiteLLM):
+# HELIX_WHISPER_BASE_URL=http://192.168.88.252:4000/v1
+# HELIX_WHISPER_API_KEY=sk-...        # virtual key LiteLLM
+# HELIX_WHISPER_MODEL=whisper         # model_name из LiteLLM config, не whisper-1
+#
+# Вариант C — тот же litellm-провайдер из профиля (HELIX_WHISPER_USE_PROFILE_LITELLM=true):
+# HELIX_WHISPER_MODEL=whisper
+#
+# Вариант D — локально на машине с агентом (без облака, нужен ffmpeg):
+# uv sync --extra voice
+# HELIX_WHISPER_BACKEND=local
+# HELIX_WHISPER_LOCAL_MODEL=base      # tiny | base | small | medium | large-v3
+# HELIX_WHISPER_LOCAL_DEVICE=cpu        # cuda для GPU
+# HELIX_WHISPER_LOCAL_COMPUTE_TYPE=int8 # float16 на GPU
+# HELIX_WHISPER_AUTO_DOWNLOAD=true      # скачать модель при старте бота (по умолчанию)
+# HELIX_WHISPER_LOCAL_DOWNLOAD_ROOT=    # каталог кэша (по умолчанию ~/.helix/models/whisper)
+# HELIX_TELEGRAM_VOICE_LANGUAGE=ru
+#
+# HELIX_WHISPER_BACKEND=auto            # local если установлен faster-whisper, иначе API
+# HELIX_TELEGRAM_VOICE_ENABLED=true
+
+# --- Telegram files (photos, documents) ---
+# HELIX_TELEGRAM_FILES_ENABLED=true
+# HELIX_TELEGRAM_MAX_FILE_MB=20
+# HELIX_TELEGRAM_MEDIA_GROUP_DELAY_MS=800  # пауза перед обработкой альбома
+# HELIX_TELEGRAM_VISION_MODEL=smart      # имя модели в LiteLLM с поддержкой vision
+# Требуются также LITELLM_API_KEY + LITELLM_API_BASE (или helix models setup)
+
+# --- Browser (optional: uv sync --extra browser) ---
+ENABLE_BROWSER_TOOLS=true
+BROWSER_HEADLESS=true
+BROWSER_ALLOWED_HOSTS=
+
+# --- Web search (helix search configure) ---
+# FIRECRAWL_API_KEY=fc-...
+# SEARXNG_BASE_URL=http://127.0.0.1:8080
+
+# Profile secrets in config.yaml: use ${OPENAI_API_KEY} or ${ENV:OPENAI_API_KEY}

helixagentai-0.1.3/.gitignore

@@ -0,0 +1,86 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+.virtualenvs/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Logs
+logs/
+*.log
+
+# Data and databases
+data/
+*.db
+*.sqlite
+*.sqlite3
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# ChromaDB
+chroma_data/
+**/vector_db/
+**/skills_db/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Docker
+.docker/
+
+# Temporary files
+*.tmp
+*.temp
+.cache/
+.idea
+
+# Local experiments (not part of Helix product)
+mcp_registry_system.py
+mcp_registry_tool.sh
+mcp_system_config.json
+MCP_REGISTRY_SYSTEM_REPORT.md
+
+# Helix local runtime
+.helix/
+.langgraph_api/
+.pid

helixagentai-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helix Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

helixagentai-0.1.3/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: HelixAgentAi
+Version: 0.1.3
+Summary: Self-improving AI agent with memory, skills, MCP, CLI, and TUI
+Project-URL: Homepage, https://helix-agent.ru
+Project-URL: Documentation, https://helix-agent.ru
+Project-URL: Repository, https://github.com/javded-itres/HelixAgent
+Project-URL: Issues, https://github.com/javded-itres/HelixAgent/issues
+Project-URL: Changelog, https://github.com/javded-itres/HelixAgent/blob/master/docs/CHANGELOG.md
+Author: Pavel Lukyanov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,langgraph,llm,mcp,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: croniter>=2.0.0
+Requires-Dist: dishka>=1.10.1
+Requires-Dist: fastapi>=0.136.3
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langgraph-checkpoint>=4.0.0
+Requires-Dist: langgraph>=1.2.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=0.80.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn>=0.48.0
+Provides-Extra: all
+Requires-Dist: aiogram>=3.15.0; extra == 'all'
+Requires-Dist: faster-whisper>=1.1.0; extra == 'all'
+Requires-Dist: playwright>=1.49.0; extra == 'all'
+Requires-Dist: psutil>=6.0.0; extra == 'all'
+Requires-Dist: pypdf>=4.0.0; extra == 'all'
+Requires-Dist: textual-serve>=1.1.3; extra == 'all'
+Provides-Extra: browser
+Requires-Dist: playwright>=1.49.0; extra == 'browser'
+Provides-Extra: telegram
+Requires-Dist: aiogram>=3.15.0; extra == 'telegram'
+Requires-Dist: pypdf>=4.0.0; extra == 'telegram'
+Provides-Extra: tui-web
+Requires-Dist: textual-serve>=1.1.3; extra == 'tui-web'
+Provides-Extra: voice
+Requires-Dist: faster-whisper>=1.1.0; extra == 'voice'
+Provides-Extra: windows
+Requires-Dist: psutil>=6.0.0; extra == 'windows'
+Description-Content-Type: text/markdown
+
+# Helix — Self-Improving AI Agent
+
+**Helix** is a self-improving AI agent with persistent memory, a skills system, tool calling, MCP integration, and multiple interfaces: CLI, TUI, API gateway, and Telegram.
+
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-en%20%7C%20ru-blue)](docs/README.md)
+
+**Website:** [helix-agent.ru](https://helix-agent.ru) · **GitHub:** [javded-itres/HelixAgent](https://github.com/javded-itres/HelixAgent) · **Documentation:** [English](docs/en/README.md) · [Русский](docs/ru/README.md) · **Donate:** [support the project](https://messenger.online.sberbank.ru/sl/uwKJ687QKl7d1a1Ui)
+
+---
+
+## Features
+
+- **Tool calling** — files, shell, web, code execution, optional Playwright browser tools
+- **Persistent memory** — SQLite conversations + ChromaDB semantic search
+- **Skills** — markdown skills with auto-generation and hub catalogs (ClawHub, Hermes, Claude plugins)
+- **MCP** — configure and assign Model Context Protocol servers per agent
+- **Multi-provider** — Ollama, LiteLLM, OpenAI, Groq, and any OpenAI-compatible API
+- **Interfaces** — `helix tui`, `helix chat-command`, `helix run`, `helix gateway`
+- **Security** — API keys, rate limits, command whitelist, confirmation prompts
+- **Operations** — `helix doctor`, `helix logs`, background gateway supervisor, Docker
+
+---
+
+## Quick start
+
+### Install
+
+**PyPI** (Python 3.12+). Package: `HelixAgentAi` (HelixAgent), command: `helix`:
+
+```bash
+pipx install HelixAgentAi          # global CLI (recommended)
+# or in a venv:
+pip install HelixAgentAi
+pip install "HelixAgentAi[all]"    # telegram + browser + tui-web
+```
+
+Do not use `pip install helix` — that is a different package on PyPI.
+
+**From source:**
+
+```bash
+git clone https://github.com/javded-itres/HelixAgent.git
+cd HelixAgent
+./scripts/install.sh          # macOS / Linux
+# Windows: .\scripts\install.ps1
+
+helix version
+helix doctor
+```
+
+Publishing: [docs/en/PYPI.md](docs/en/PYPI.md)
+
+Developer install:
+
+```bash
+uv sync && uv pip install -e .
+cp .env.example .env
+```
+
+Full guide: [docs/en/INSTALLATION.md](docs/en/INSTALLATION.md)
+
+### Configure and run
+
+```bash
+helix models setup
+helix tui                    # recommended UI
+# or:
+helix chat-command
+helix run "What is in this repo?"
+helix gateway start
+```
+
+---
+
+## Documentation (English)
+
+| Topic | Link |
+|-------|------|
+| Install & update | [INSTALLATION.md](docs/en/INSTALLATION.md) |
+| **CLI reference** | [CLI.md](docs/en/CLI.md) |
+| **Slash commands `/`** | [SLASH_COMMANDS.md](docs/en/SLASH_COMMANDS.md) |
+| TUI | [TUI.md](docs/en/TUI.md) |
+| Configuration | [CONFIGURATION.md](docs/en/CONFIGURATION.md) |
+| Skill Hub | [HUB.md](docs/en/HUB.md) |
+| API Gateway | [GATEWAY.md](docs/en/GATEWAY.md) |
+| Logs | [LOGS.md](docs/en/LOGS.md) |
+| Doctor | [DOCTOR.md](docs/en/DOCTOR.md) |
+| Security | [SECURITY.md](docs/en/SECURITY.md) |
+| Deployment | [DEPLOYMENT.md](docs/en/DEPLOYMENT.md) |
+| Troubleshooting | [TROUBLESHOOTING.md](docs/en/TROUBLESHOOTING.md) |
+| Architecture | [ARCHITECTURE.md](docs/en/ARCHITECTURE.md) |
+
+## Документация (русский)
+
+| Тема | Ссылка |
+|------|--------|
+| Установка | [INSTALLATION.md](docs/ru/INSTALLATION.md) |
+| CLI | [CLI.md](docs/ru/CLI.md) |
+| Слэш-команды | [SLASH_COMMANDS.md](docs/ru/SLASH_COMMANDS.md) |
+| Начало | [START_HERE.md](docs/ru/START_HERE.md) |
+
+---
+
+## CLI at a glance
+
+```bash
+helix tui                          # main UI
+helix run "query"                  # one-shot
+helix models setup                 # providers
+helix hub browse                   # external skills
+helix mcp setup                    # MCP servers
+helix gateway start|status|stop|reload
+helix logs [-s agent] [-f]
+helix doctor [--fix]
+helix install | helix update
+```
+
+In TUI/Telegram, type `/help` for slash commands. See [docs/en/SLASH_COMMANDS.md](docs/en/SLASH_COMMANDS.md).
+
+---
+
+## Architecture
+
+```
+HelixAgent → run_agent_loop() (core/agent_execution.py)
+           → LangGraph / AgentLoop
+```
+
+| Layer | Path |
+|-------|------|
+| Execution | `core/agent_execution.py` |
+| Events | `core/agent_events.py` |
+| Tools | `core/tools/` |
+| Memory | `core/memory/` |
+| CLI | `cli/main.py` |
+| Gateway | `api/gateway.py` |
+
+Details: [docs/en/ARCHITECTURE.md](docs/en/ARCHITECTURE.md)
+
+---
+
+## Docker
+
+```bash
+docker compose up -d
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Run tests before PRs: `uv run pytest -m "not llm"`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

helixagentai-0.1.3/README.md

@@ -0,0 +1,160 @@
+# Helix — Self-Improving AI Agent
+
+**Helix** is a self-improving AI agent with persistent memory, a skills system, tool calling, MCP integration, and multiple interfaces: CLI, TUI, API gateway, and Telegram.
+
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-en%20%7C%20ru-blue)](docs/README.md)
+
+**Website:** [helix-agent.ru](https://helix-agent.ru) · **GitHub:** [javded-itres/HelixAgent](https://github.com/javded-itres/HelixAgent) · **Documentation:** [English](docs/en/README.md) · [Русский](docs/ru/README.md) · **Donate:** [support the project](https://messenger.online.sberbank.ru/sl/uwKJ687QKl7d1a1Ui)
+
+---
+
+## Features
+
+- **Tool calling** — files, shell, web, code execution, optional Playwright browser tools
+- **Persistent memory** — SQLite conversations + ChromaDB semantic search
+- **Skills** — markdown skills with auto-generation and hub catalogs (ClawHub, Hermes, Claude plugins)
+- **MCP** — configure and assign Model Context Protocol servers per agent
+- **Multi-provider** — Ollama, LiteLLM, OpenAI, Groq, and any OpenAI-compatible API
+- **Interfaces** — `helix tui`, `helix chat-command`, `helix run`, `helix gateway`
+- **Security** — API keys, rate limits, command whitelist, confirmation prompts
+- **Operations** — `helix doctor`, `helix logs`, background gateway supervisor, Docker
+
+---
+
+## Quick start
+
+### Install
+
+**PyPI** (Python 3.12+). Package: `HelixAgentAi` (HelixAgent), command: `helix`:
+
+```bash
+pipx install HelixAgentAi          # global CLI (recommended)
+# or in a venv:
+pip install HelixAgentAi
+pip install "HelixAgentAi[all]"    # telegram + browser + tui-web
+```
+
+Do not use `pip install helix` — that is a different package on PyPI.
+
+**From source:**
+
+```bash
+git clone https://github.com/javded-itres/HelixAgent.git
+cd HelixAgent
+./scripts/install.sh          # macOS / Linux
+# Windows: .\scripts\install.ps1
+
+helix version
+helix doctor
+```
+
+Publishing: [docs/en/PYPI.md](docs/en/PYPI.md)
+
+Developer install:
+
+```bash
+uv sync && uv pip install -e .
+cp .env.example .env
+```
+
+Full guide: [docs/en/INSTALLATION.md](docs/en/INSTALLATION.md)
+
+### Configure and run
+
+```bash
+helix models setup
+helix tui                    # recommended UI
+# or:
+helix chat-command
+helix run "What is in this repo?"
+helix gateway start
+```
+
+---
+
+## Documentation (English)
+
+| Topic | Link |
+|-------|------|
+| Install & update | [INSTALLATION.md](docs/en/INSTALLATION.md) |
+| **CLI reference** | [CLI.md](docs/en/CLI.md) |
+| **Slash commands `/`** | [SLASH_COMMANDS.md](docs/en/SLASH_COMMANDS.md) |
+| TUI | [TUI.md](docs/en/TUI.md) |
+| Configuration | [CONFIGURATION.md](docs/en/CONFIGURATION.md) |
+| Skill Hub | [HUB.md](docs/en/HUB.md) |
+| API Gateway | [GATEWAY.md](docs/en/GATEWAY.md) |
+| Logs | [LOGS.md](docs/en/LOGS.md) |
+| Doctor | [DOCTOR.md](docs/en/DOCTOR.md) |
+| Security | [SECURITY.md](docs/en/SECURITY.md) |
+| Deployment | [DEPLOYMENT.md](docs/en/DEPLOYMENT.md) |
+| Troubleshooting | [TROUBLESHOOTING.md](docs/en/TROUBLESHOOTING.md) |
+| Architecture | [ARCHITECTURE.md](docs/en/ARCHITECTURE.md) |
+
+## Документация (русский)
+
+| Тема | Ссылка |
+|------|--------|
+| Установка | [INSTALLATION.md](docs/ru/INSTALLATION.md) |
+| CLI | [CLI.md](docs/ru/CLI.md) |
+| Слэш-команды | [SLASH_COMMANDS.md](docs/ru/SLASH_COMMANDS.md) |
+| Начало | [START_HERE.md](docs/ru/START_HERE.md) |
+
+---
+
+## CLI at a glance
+
+```bash
+helix tui                          # main UI
+helix run "query"                  # one-shot
+helix models setup                 # providers
+helix hub browse                   # external skills
+helix mcp setup                    # MCP servers
+helix gateway start|status|stop|reload
+helix logs [-s agent] [-f]
+helix doctor [--fix]
+helix install | helix update
+```
+
+In TUI/Telegram, type `/help` for slash commands. See [docs/en/SLASH_COMMANDS.md](docs/en/SLASH_COMMANDS.md).
+
+---
+
+## Architecture
+
+```
+HelixAgent → run_agent_loop() (core/agent_execution.py)
+           → LangGraph / AgentLoop
+```
+
+| Layer | Path |
+|-------|------|
+| Execution | `core/agent_execution.py` |
+| Events | `core/agent_events.py` |
+| Tools | `core/tools/` |
+| Memory | `core/memory/` |
+| CLI | `cli/main.py` |
+| Gateway | `api/gateway.py` |
+
+Details: [docs/en/ARCHITECTURE.md](docs/en/ARCHITECTURE.md)
+
+---
+
+## Docker
+
+```bash
+docker compose up -d
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Run tests before PRs: `uv run pytest -m "not llm"`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

helixagentai-0.1.3/api/deps.py

@@ -0,0 +1,75 @@
+"""FastAPI dependencies for Helix gateway."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import Header, HTTPException
+
+from config import settings
+
+# Set by gateway lifespan
+api_key_manager = None
+rate_limiter = None
+
+
+def _extract_api_key(
+    authorization: Optional[str],
+    x_api_key: Optional[str],
+) -> Optional[str]:
+    if authorization and authorization.startswith("Bearer "):
+        return authorization[7:]
+    if x_api_key:
+        return x_api_key
+    return None
+
+
+async def _validate_key(api_key: str, *, default_limit: int) -> dict:
+    if api_key_manager is None:
+        raise HTTPException(status_code=503, detail="API key manager not initialized")
+
+    key_info = await api_key_manager.validate_api_key(api_key)
+    if not key_info:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+
+    limit = int(key_info.get("rate_limit") or default_limit)
+    key_hash = api_key_manager.hash_key(api_key)
+    if rate_limiter and not rate_limiter.check_rate_limit(key_hash, limit):
+        raise HTTPException(status_code=429, detail="Rate limit exceeded")
+
+    return key_info
+
+
+async def verify_api_key(
+    authorization: Optional[str] = Header(None),
+    x_api_key: Optional[str] = Header(None),
+) -> Optional[dict]:
+    """Optional auth for public /v1 routes when require_auth is disabled."""
+    if not settings.effective_require_auth:
+        api_key = _extract_api_key(authorization, x_api_key)
+        if not api_key:
+            return None
+        return await _validate_key(api_key, default_limit=settings.rate_limit_rpm)
+
+    api_key = _extract_api_key(authorization, x_api_key)
+    if not api_key:
+        raise HTTPException(status_code=401, detail="API key required")
+    return await _validate_key(api_key, default_limit=settings.rate_limit_rpm)
+
+
+async def verify_admin_key(
+    authorization: Optional[str] = Header(None),
+    x_api_key: Optional[str] = Header(None),
+) -> dict:
+    """Admin routes always require a valid admin API key."""
+    from core.security.permissions import PermissionChecker
+
+    api_key = _extract_api_key(authorization, x_api_key)
+    if not api_key:
+        raise HTTPException(status_code=401, detail="Admin API key required")
+
+    key_info = await _validate_key(api_key, default_limit=settings.admin_rate_limit_rpm)
+    checker = PermissionChecker(key_info["permissions"])
+    if not checker.is_admin():
+        raise HTTPException(status_code=403, detail="Admin permission required")
+    return key_info