navaia-code 1.0.50__py3-none-any.whl

navaia/config/providers.py

@@ -0,0 +1,234 @@
+"""Provider profiles for multi-backend LLM configuration.
+
+Connection details are resolved from three layers (highest wins):
+
+    1. Environment variables (NAVAIA_<PROVIDER>_BASE_URL, etc.)
+    2. Config files (~/.navaia/config.json, .navaia/config.json)
+    3. Built-in defaults in this file
+
+Example ~/.navaia/config.json:
+    {
+        "provider": "internal",
+        "providers": {
+            "internal": {
+                "base_url": "https://ngx.tawakkalna.nic.gov.sa/v1",
+                "model": "/models/gpt-oss-120b"
+            }
+        }
+    }
+
+Example .env:
+    NAVAIA_PROVIDER=internal
+    NAVAIA_INTERNAL_BASE_URL=https://ngx.tawakkalna.nic.gov.sa/v1
+    NAVAIA_INTERNAL_MODEL=/models/gpt-oss-120b
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, replace
+
+
+@dataclass(frozen=True)
+class ProviderProfile:
+    """Immutable connection profile for an LLM provider."""
+
+    name: str
+    base_url: str
+    model: str
+    api_key_env: str        # env var name that holds the key (empty = no key needed)
+    default_api_key: str    # fallback when env var is unset (e.g. "empty" for internal)
+    timeout: float
+    verify_ssl: bool
+    retry_on_rate_limit: bool
+
+
+# Built-in defaults — last-resort fallback only.
+_DEFAULTS: dict[str, ProviderProfile] = {
+    "openrouter": ProviderProfile(
+        name="openrouter",
+        base_url="https://openrouter.ai/api/v1",
+        # GPT-OSS-120B via OpenRouter.
+        # Override via NAVAIA_OPENROUTER_MODEL (e.g. moonshotai/kimi-k2,
+        # minimax/minimax-m2, anthropic/claude-opus-4, openai/gpt-4o, etc.)
+        model="gpt-oss-120b",
+        api_key_env="OPENROUTER_API_KEY",
+        default_api_key="",
+        timeout=120.0,
+        verify_ssl=True,
+        retry_on_rate_limit=True,
+    ),
+    "internal": ProviderProfile(
+        name="internal",
+        base_url="https://ngx.tawakkalna.nic.gov.sa/v1",
+        model="/models/gpt-oss-120b",
+        api_key_env="",
+        default_api_key="empty",
+        timeout=55.0,  # ngx reverse proxy has 60s timeout
+        verify_ssl=False,
+        retry_on_rate_limit=False,
+    ),
+    # Local Qwen (or any OpenAI-compatible server you host yourself:
+    # vLLM, llama.cpp --server, LM Studio, text-generation-webui, etc.).
+    # Placeholder URL points at vLLM's default port — override via
+    # NAVAIA_QWEN_BASE_URL / NAVAIA_QWEN_MODEL in your .env.
+    "qwen": ProviderProfile(
+        name="qwen",
+        base_url="http://localhost:8000/v1",
+        model="Qwen/Qwen2.5-7B-Instruct",
+        api_key_env="QWEN_API_KEY",
+        default_api_key="empty",
+        timeout=300.0,
+        verify_ssl=True,
+        retry_on_rate_limit=False,
+    ),
+    # Ollama — local models served on the default Ollama port.
+    # Override via NAVAIA_OLLAMA_BASE_URL / NAVAIA_OLLAMA_MODEL.
+    "ollama": ProviderProfile(
+        name="ollama",
+        base_url="http://localhost:11434/v1",
+        model="qwen2.5:7b",
+        api_key_env="",
+        default_api_key="ollama",
+        timeout=300.0,
+        verify_ssl=True,
+        retry_on_rate_limit=False,
+    ),
+}
+
+DEFAULT_PROVIDER = "openrouter"
+
+# Populated by load_provider_overrides() at startup
+_config_overrides: dict[str, dict] = {}
+
+
+def load_provider_overrides(config: dict) -> None:
+    """Load provider overrides from merged config (call once at startup).
+
+    Expects the "providers" key from the merged config dict:
+        {"providers": {"internal": {"base_url": "...", "model": "..."}}}
+    """
+    global _config_overrides
+    _config_overrides = dict(config.get("providers", {}))
+
+
+def _apply_overrides(profile: ProviderProfile) -> ProviderProfile:
+    """Apply config-file and env-var overrides to a default profile.
+
+    Priority: env vars > config files > built-in defaults.
+    """
+    name = profile.name
+    prefix = f"NAVAIA_{name.upper()}_"
+
+    # Start with config-file overrides
+    cfg = dict(_config_overrides.get(name, {}))
+
+    # Env vars override config files
+    overrides: dict = {}
+
+    # base_url
+    env_url = os.environ.get(f"{prefix}BASE_URL")
+    if env_url:
+        overrides["base_url"] = env_url
+    elif "base_url" in cfg:
+        overrides["base_url"] = cfg["base_url"]
+
+    # model
+    env_model = os.environ.get(f"{prefix}MODEL")
+    if env_model:
+        overrides["model"] = env_model
+    elif "model" in cfg:
+        overrides["model"] = cfg["model"]
+
+    # timeout
+    env_timeout = os.environ.get(f"{prefix}TIMEOUT")
+    if env_timeout:
+        try:
+            overrides["timeout"] = float(env_timeout)
+        except ValueError:
+            pass
+    elif "timeout" in cfg:
+        try:
+            overrides["timeout"] = float(cfg["timeout"])
+        except (ValueError, TypeError):
+            pass
+
+    # api_key_env
+    if "api_key_env" in cfg:
+        overrides["api_key_env"] = cfg["api_key_env"]
+
+    # verify_ssl
+    env_ssl = os.environ.get(f"{prefix}VERIFY_SSL")
+    if env_ssl is not None:
+        overrides["verify_ssl"] = env_ssl.lower() in ("1", "true", "yes")
+    elif "verify_ssl" in cfg:
+        overrides["verify_ssl"] = bool(cfg["verify_ssl"])
+
+    if not overrides:
+        return profile
+
+    return replace(profile, **overrides)
+
+
+def resolve_provider(provider_name: str = "") -> ProviderProfile:
+    """Resolve a provider profile by name, with all overrides applied.
+
+    Falls back to NAVAIA_PROVIDER env var, then DEFAULT_PROVIDER.
+    """
+    name = provider_name or os.environ.get("NAVAIA_PROVIDER", DEFAULT_PROVIDER)
+    name = name.strip().lower()
+
+    if name not in _DEFAULTS:
+        valid = ", ".join(sorted(_DEFAULTS))
+        raise ValueError(
+            f"Unknown provider '{name}'. Available providers: {valid}"
+        )
+
+    return _apply_overrides(_DEFAULTS[name])
+
+
+def resolve_api_key(profile: ProviderProfile) -> str:
+    """Resolve the API key for a provider profile.
+
+    Priority: provider-specific env > OPENAI_API_KEY (only when
+    OPENAI_BASE_URL is also set) > profile default.
+    """
+    # Provider-specific env var takes priority
+    if profile.api_key_env:
+        if key := os.environ.get(profile.api_key_env):
+            return key
+    # Generic overrides only apply when the user also overrides the URL
+    if os.environ.get("OPENAI_BASE_URL") or os.environ.get("ANTHROPIC_BASE_URL"):
+        if key := os.environ.get("OPENAI_API_KEY"):
+            return key
+        if key := os.environ.get("ANTHROPIC_API_KEY"):
+            return key
+    # Profile default (e.g. "empty" for internal, "ollama" for local)
+    return profile.default_api_key
+
+
+def resolve_base_url(profile: ProviderProfile) -> str:
+    """Resolve the base URL (profile already has overrides applied)."""
+    return profile.base_url
+
+
+def resolve_model(profile: ProviderProfile) -> str:
+    """Resolve the model identifier.
+
+    Priority: provider-scoped override (NAVAIA_<NAME>_MODEL, already applied
+    in _apply_overrides) > generic ANTHROPIC_MODEL/OPENAI_MODEL *only* when
+    the user also overrode the base URL (i.e. they are deliberately pointing
+    at a non-default backend) > profile value.
+
+    The scoping matters: an `ANTHROPIC_MODEL` left in a shell profile must
+    not silently hijack openrouter/qwen/ollama/internal.
+    """
+    has_url_override = bool(
+        os.environ.get("OPENAI_BASE_URL") or os.environ.get("ANTHROPIC_BASE_URL")
+    )
+    if has_url_override:
+        if m := os.environ.get("ANTHROPIC_MODEL"):
+            return m
+        if m := os.environ.get("OPENAI_MODEL"):
+            return m
+    return profile.model

navaia/config/settings.py

@@ -0,0 +1,113 @@
+"""Merged settings from global config, project config, and env overrides."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .env import get_env_overrides
+from .global_config import load_global_config
+from .project_config import load_project_config
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Immutable settings object built from merged configuration layers."""
+
+    # Permission rules
+    allowed_tools: tuple[str, ...] = ()
+    denied_tools: tuple[str, ...] = ()
+
+    # Hooks
+    hooks: dict = field(default_factory=dict)
+
+    # Provider (openrouter, internal)
+    provider: str = ""
+
+    # Model preferences
+    default_model: str = ""
+
+    # UI preferences
+    vim_mode: bool = False
+    theme: str = "dark"
+
+    # Thinking
+    always_thinking_enabled: bool = False
+    max_thinking_tokens: int = 31999
+
+    # Other
+    verbose: bool = False
+
+
+# Keys in JSON configs that map directly to Settings fields.
+_BOOL_FIELDS = frozenset({"vim_mode", "always_thinking_enabled", "verbose"})
+_INT_FIELDS = frozenset({"max_thinking_tokens"})
+_STR_FIELDS = frozenset({"provider", "default_model", "theme"})
+_TUPLE_STR_FIELDS = frozenset({"allowed_tools", "denied_tools"})
+_DICT_FIELDS = frozenset({"hooks"})
+
+
+def _coerce(key: str, value: object) -> object:
+    """Coerce a raw config value to the type expected by Settings."""
+    if key in _BOOL_FIELDS:
+        return bool(value)
+    if key in _INT_FIELDS:
+        return int(value)
+    if key in _STR_FIELDS:
+        return str(value)
+    if key in _TUPLE_STR_FIELDS:
+        if isinstance(value, (list, tuple)):
+            return tuple(str(v) for v in value)
+        return ()
+    if key in _DICT_FIELDS:
+        return dict(value) if isinstance(value, dict) else {}
+    return value
+
+
+_ALL_FIELDS = _BOOL_FIELDS | _INT_FIELDS | _STR_FIELDS | _TUPLE_STR_FIELDS | _DICT_FIELDS
+
+
+def _merge_layer(accumulated: dict, layer: dict) -> dict:
+    """Return a new dict with *layer* values merged on top of *accumulated*.
+
+    Only keys that correspond to Settings fields are kept.
+    """
+    result = dict(accumulated)
+    for key, value in layer.items():
+        if key in _ALL_FIELDS:
+            result[key] = _coerce(key, value)
+    return result
+
+
+def load_settings(cwd: str) -> Settings:
+    """Load and merge settings from global config, project config, and env.
+
+    Precedence (highest wins): env overrides > project config > global config.
+    Also loads provider connection overrides from the "providers" key in
+    config files so that base_url, model, timeout, etc. are configurable.
+    """
+    from .providers import load_provider_overrides
+
+    global_cfg = load_global_config()
+    project_cfg = load_project_config(cwd)
+
+    # Merge provider overrides: global < project (project wins)
+    provider_overrides: dict = {}
+    if "providers" in global_cfg:
+        provider_overrides.update(global_cfg["providers"])
+    if "providers" in project_cfg:
+        for name, overrides in project_cfg["providers"].items():
+            if name in provider_overrides:
+                merged_provider = dict(provider_overrides[name])
+                merged_provider.update(overrides)
+                provider_overrides[name] = merged_provider
+            else:
+                provider_overrides[name] = overrides
+
+    load_provider_overrides({"providers": provider_overrides})
+
+    # Merge Settings fields (excluding "providers" which is handled above)
+    merged: dict = {}
+    merged = _merge_layer(merged, global_cfg)
+    merged = _merge_layer(merged, project_cfg)
+    merged = _merge_layer(merged, get_env_overrides())
+    return Settings(**merged)

navaia/context/cache.py

@@ -0,0 +1,29 @@
+"""Cache boundary splitting for Anthropic prompt caching.
+
+The system prompt is split at a dynamic boundary marker so that the static
+portion can be sent with ``cache_control`` to take advantage of the 5-minute
+prompt-cache TTL.
+"""
+
+from __future__ import annotations
+
+DYNAMIC_BOUNDARY = "__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__"
+
+
+def split_system_prompt_for_cache(system: str) -> tuple[str, str]:
+    """Split *system* at ``DYNAMIC_BOUNDARY``.
+
+    Returns ``(static, dynamic)`` where:
+    - *static* — everything before the boundary (gets ``cache_control``).
+    - *dynamic* — everything after the boundary (changes per session).
+
+    If the boundary is not found the entire prompt is treated as static and
+    *dynamic* is an empty string.
+    """
+    idx = system.find(DYNAMIC_BOUNDARY)
+    if idx == -1:
+        return system, ""
+
+    static = system[:idx].rstrip()
+    dynamic = system[idx + len(DYNAMIC_BOUNDARY):].lstrip()
+    return static, dynamic

navaia/context/claudemd.py

@@ -0,0 +1,252 @@
+"""NAVAIA.md hierarchy discovery — mirrors claudeMd.ts.
+
+Discovers, parses, and combines NAVAIA.md (and legacy CLAUDE.md) files
+from multiple locations in priority order (lower priority first,
+deeper directories = higher priority).
+
+Backwards-compatible: .claude/ paths are checked as fallbacks so existing
+Claude Code setups work without changes.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+def find_git_root(cwd: str) -> Optional[Path]:
+    """Walk up from *cwd* to find the nearest directory containing .git."""
+    current = Path(cwd).resolve()
+    while True:
+        if (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def discover_context_files(cwd: str) -> list[tuple[Path, str]]:
+    """Return (path, content) pairs in ascending priority order.
+
+    Discovery order (low -> high priority):
+      1. /etc/navaia/NAVAIA.md           (managed / system-wide)
+      2. ~/.navaia/NAVAIA.md             (user global)
+      3. For each directory from git root down to cwd:
+         a. NAVAIA.md  (or CLAUDE.md fallback)
+         b. .navaia/NAVAIA.md  (or .claude/CLAUDE.md fallback)
+         c. .navaia/rules/*.md  (or .claude/rules/*.md fallback)
+         d. .navaia/NAVAIA.local.md  (or .claude/CLAUDE.local.md fallback)
+    """
+    results: list[tuple[Path, str]] = []
+
+    # --- 1. Managed (system-wide) ---
+    _try_append(Path("/etc/navaia/NAVAIA.md"), results)
+
+    # --- 2. User global ---
+    _try_append(Path.home() / ".navaia" / "NAVAIA.md", results)
+
+    # --- 3. Per-directory from git root down to cwd ---
+    git_root = find_git_root(cwd)
+    dirs_to_scan = _dirs_from_root_to_cwd(git_root, cwd)
+
+    for directory in dirs_to_scan:
+        # Root-level context file
+        _try_first(
+            [directory / "NAVAIA.md", directory / "CLAUDE.md"],
+            results,
+        )
+        # Nested config directory
+        _try_first(
+            [directory / ".navaia" / "NAVAIA.md", directory / ".claude" / "CLAUDE.md"],
+            results,
+        )
+        # Rules directory
+        _collect_rules_first(
+            [directory / ".navaia" / "rules", directory / ".claude" / "rules"],
+            results,
+        )
+        # Local overrides
+        _try_first(
+            [directory / ".navaia" / "NAVAIA.local.md", directory / ".claude" / "CLAUDE.local.md"],
+            results,
+        )
+
+    return results
+
+
+# Keep the old name as an alias for any existing callers
+discover_claude_md_files = discover_context_files
+
+
+# ---------------------------------------------------------------------------
+# Parsing helpers
+# ---------------------------------------------------------------------------
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+_INCLUDE_RE = re.compile(r"^@include\s+(.+)$", re.MULTILINE)
+
+
+def parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Extract optional YAML frontmatter from *content*.
+
+    Returns (metadata_dict, body_without_frontmatter).
+    If no frontmatter is present, metadata_dict is empty.
+    """
+    match = _FRONTMATTER_RE.match(content)
+    if not match:
+        return {}, content
+
+    raw_yaml = match.group(1)
+    try:
+        metadata = yaml.safe_load(raw_yaml) or {}
+    except yaml.YAMLError:
+        metadata = {}
+
+    body = content[match.end():]
+    return metadata, body
+
+
+def strip_html_comments(text: str) -> str:
+    """Remove ``<!-- ... -->`` comments from *text*."""
+    return _HTML_COMMENT_RE.sub("", text)
+
+
+def process_includes(
+    text: str,
+    base_dir: Path,
+    visited: set[Path] | None = None,
+) -> str:
+    """Recursively resolve ``@include <relative-path>`` directives.
+
+    *visited* tracks already-included paths to prevent cycles.
+    """
+    if visited is None:
+        visited = set()
+
+    def _replacer(match: re.Match) -> str:
+        rel_path = match.group(1).strip()
+        target = (base_dir / rel_path).resolve()
+
+        if target in visited or not target.is_file():
+            return ""
+
+        visited.add(target)
+        included = _read_text(target)
+        if included is None:
+            return ""
+
+        # Recurse so included files can themselves include others.
+        return process_includes(included, target.parent, visited)
+
+    return _INCLUDE_RE.sub(_replacer, text)
+
+
+def get_user_context(cwd: str) -> str:
+    """Combine all discovered context files into a single context string.
+
+    Each file's content is processed (frontmatter stripped, comments removed,
+    includes resolved) and separated by a blank line.
+    """
+    files = discover_context_files(cwd)
+    if not files:
+        return ""
+
+    sections: list[str] = []
+    for path, raw_content in files:
+        _meta, body = parse_frontmatter(raw_content)
+        body = strip_html_comments(body)
+        body = process_includes(body, path.parent, set())
+        body = body.strip()
+        if body:
+            sections.append(body)
+
+    return "\n\n".join(sections)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_text(path: Path) -> Optional[str]:
+    """Read a file as UTF-8 text, returning None on any error."""
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _try_append(path: Path, results: list[tuple[Path, str]]) -> None:
+    """Append *(path, content)* to *results* if *path* is a readable file."""
+    content = _read_text(path)
+    if content is not None:
+        results.append((path, content))
+
+
+def _try_first(
+    candidates: list[Path],
+    results: list[tuple[Path, str]],
+) -> None:
+    """Try each candidate path in order; append the first one that exists."""
+    for path in candidates:
+        content = _read_text(path)
+        if content is not None:
+            results.append((path, content))
+            return
+
+
+def _collect_rules(rules_dir: Path, results: list[tuple[Path, str]]) -> None:
+    """Append all ``*.md`` files in *rules_dir* sorted alphabetically."""
+    if not rules_dir.is_dir():
+        return
+    for md_file in sorted(rules_dir.glob("*.md")):
+        if md_file.is_file():
+            _try_append(md_file, results)
+
+
+def _collect_rules_first(
+    candidates: list[Path],
+    results: list[tuple[Path, str]],
+) -> None:
+    """Try each rules directory candidate; use the first one that has .md files."""
+    for rules_dir in candidates:
+        if rules_dir.is_dir() and any(rules_dir.glob("*.md")):
+            _collect_rules(rules_dir, results)
+            return
+
+
+def _dirs_from_root_to_cwd(
+    git_root: Optional[Path],
+    cwd: str,
+) -> list[Path]:
+    """Return the list of directories from *git_root* down to *cwd* (inclusive).
+
+    If *git_root* is None, only *cwd* itself is returned.
+    """
+    resolved_cwd = Path(cwd).resolve()
+
+    if git_root is None:
+        return [resolved_cwd]
+
+    git_root = git_root.resolve()
+
+    # Build path from git_root down to cwd.
+    try:
+        relative = resolved_cwd.relative_to(git_root)
+    except ValueError:
+        # cwd is not under git_root (shouldn't happen but be safe).
+        return [resolved_cwd]
+
+    dirs: list[Path] = [git_root]
+    accumulated = git_root
+    for part in relative.parts:
+        accumulated = accumulated / part
+        if accumulated != git_root:
+            dirs.append(accumulated)
+
+    return dirs