HelixAgentAi 0.1.3__py3-none-any.whl

.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}

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

api/errors.py

@@ -0,0 +1,58 @@
+"""OpenAI-compatible error mapping for the API gateway."""
+
+from __future__ import annotations
+
+from fastapi import HTTPException
+
+
+def openai_error_body(
+    message: str,
+    *,
+    error_type: str = "server_error",
+    code: str = "internal_error",
+) -> dict:
+    return {
+        "error": {
+            "message": message,
+            "type": error_type,
+            "code": code,
+        }
+    }
+
+
+def agent_error_to_http(exc: Exception, *, default_status: int = 500) -> HTTPException:
+    """Map agent/runtime exceptions to OpenAI-style HTTPException detail."""
+    if isinstance(exc, HTTPException):
+        return exc
+
+    message = str(exc) or "Unknown error"
+    lower = message.lower()
+    status = default_status
+    error_type = "server_error"
+    code = "internal_error"
+
+    if "not initialized" in lower or "not ready" in lower:
+        status = 503
+        error_type = "service_unavailable"
+        code = "agent_unavailable"
+    elif "permission" in lower or "forbidden" in lower:
+        status = 403
+        error_type = "permission_denied"
+        code = "insufficient_permissions"
+    elif "confirmation" in lower or "denied" in lower:
+        status = 409
+        error_type = "confirmation_required"
+        code = "confirmation_denied"
+    elif "plan review" in lower or "review" in lower and "not found" in lower:
+        status = 404
+        error_type = "invalid_request_error"
+        code = "plan_review_not_found"
+    elif "timeout" in lower:
+        status = 504
+        error_type = "timeout"
+        code = "gateway_timeout"
+
+    return HTTPException(
+        status_code=status,
+        detail=openai_error_body(message, error_type=error_type, code=code),
+    )