AI/ontology_platform/platform/config.py

"""Platform-level configuration.

Thin layer over OntoCast's ``Config`` that adds:

1. A single explicit ``PHASE`` knob. Phase 0 forces filesystem-only storage
   and ignores any Neo4j/Fuseki environment variables that may be present
   (they belong to Phase 4 — see ``docs/통합설계서.md`` §5).
2. A platform-side ``working_directory`` default so the user does not have
   to remember the legacy ``ONTOCAST_*`` env-var prefix.
3. Hook points for future phases (LLM budgets, robots policy, etc.).

The OntoCast vendored copy itself is not modified by this module — we only
build a ``Config`` instance and pass it to ``ToolBox``.
"""

from __future__ import annotations

import logging
import sys
from enum import IntEnum
from pathlib import Path
from typing import Literal

from pydantic import Field, model_validator
from pydantic_settings import BaseSettings, SettingsConfigDict

# Make the vendored OntoCast package importable without users having to
# install it into the environment. This mirrors what tests/unit/test_*.py
# already do; centralizing it here keeps any module that imports our
# Settings consistent.
_REPO_ROOT = Path(__file__).resolve().parents[1]
_VENDORED_ONTOCAST = _REPO_ROOT / "vendored" / "ontocast"
if str(_VENDORED_ONTOCAST) not in sys.path:
    sys.path.insert(0, str(_VENDORED_ONTOCAST))

# Late import — OntoCast must be on sys.path first.
from ontocast.config import (  # noqa: E402  (must follow sys.path tweak)
    Config as OntoCastConfig,
)
from ontocast.config import (  # noqa: E402
    FusekiConfig,
    LLMConfig,
    Neo4jConfig,
    PathConfig,
    ToolConfig,
)

logger = logging.getLogger(__name__)


class Phase(IntEnum):
    """Integration phase from the master design (docs/통합설계서.md §5).

    Used as a gate: features whose phase exceeds ``Settings.phase`` are
    disabled even if their environment variables are populated.
    """

    BASE = 0  # OntoCast only, filesystem storage
    TRAFILATURA = 1
    CRAWL4AI = 2
    GUARDRAILS = 3
    NEO4J_GRAPHRAG = 4
    MULTI_AGENT = 5


StorageBackend = Literal["filesystem", "fuseki", "neo4j"]


class PlatformSettings(BaseSettings):
    """Top-level platform settings, loaded from ``.env`` and the environment.

    Only fields the platform itself needs are declared here. OntoCast-specific
    settings (LLM, chunk, paths, ...) are loaded by OntoCast's own ``Config``
    via its own ``env_prefix`` conventions and merged in ``build_ontocast_config``.
    """

    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
        case_sensitive=False,
    )

    # ─── Phase gating ────────────────────────────────────────────────
    phase: Phase = Field(
        default=Phase.BASE,
        description="Current integration phase (docs/통합설계서.md §5).",
    )
    storage_backend: StorageBackend = Field(
        default="filesystem",
        description=(
            "Which storage backend to use. Phase 0 forces 'filesystem' "
            "regardless of any Neo4j/Fuseki credentials in the environment."
        ),
    )

    # ─── Paths (mirror ONTOCAST_* but with platform defaults) ────────
    working_directory: Path = Field(
        default=Path("./data/working"),
        description="Working directory for OntoCast filesystem store.",
        validation_alias="ONTOCAST_WORKING_DIRECTORY",
    )
    ontology_directory: Path | None = Field(
        default=None,
        validation_alias="ONTOCAST_ONTOLOGY_DIRECTORY",
    )

    # ─── Server ──────────────────────────────────────────────────────
    host: str = Field(default="0.0.0.0")
    port: int = Field(default=8000)
    log_level: str = Field(default="info")

    # ─── Operational policy (used from Phase 2+) ─────────────────────
    robots_policy: Literal["strict", "respect", "ignore"] = Field(
        default="respect",
        description="robots.txt 준수 정책. Phase 2 Crawl4AI 통합에서 사용.",
    )
    daily_llm_call_limit: int = Field(default=10_000)
    daily_llm_token_limit: int = Field(default=10_000_000)

    # ─── Phase 0 enforcement ─────────────────────────────────────────
    @model_validator(mode="after")
    def _enforce_phase_storage_consistency(self) -> "PlatformSettings":
        """Phase 0 forces filesystem; later phases may opt into other backends.

        Anything other than 'filesystem' before Phase 4 is treated as a
        configuration error — failing fast here is far easier to debug than
        a half-wired Neo4j connection deep inside ToolBox.
        """
        if self.phase < Phase.NEO4J_GRAPHRAG and self.storage_backend != "filesystem":
            raise ValueError(
                f"storage_backend={self.storage_backend!r} requires Phase 4+, "
                f"but PHASE={int(self.phase)}. See docs/통합설계서.md §5."
            )
        # Ensure working directory exists for filesystem mode.
        if self.storage_backend == "filesystem":
            self.working_directory.mkdir(parents=True, exist_ok=True)
        return self


def _empty_neo4j_config() -> Neo4jConfig:
    """A Neo4jConfig with no URI/auth so ToolBox skips Neo4j initialization.

    ToolBox enables Neo4j only when both ``uri`` and ``auth`` are set
    (vendored/ontocast/ontocast/toolbox.py around line 112). Returning an
    instance with both ``None`` is the canonical way to disable the backend
    even if NEO4J_* env vars happen to be populated in the shell.
    """
    cfg = Neo4jConfig()
    cfg.uri = None  # type: ignore[assignment]
    cfg.auth = None  # type: ignore[assignment]
    return cfg


def _empty_fuseki_config() -> FusekiConfig:
    """Same idea as ``_empty_neo4j_config`` for Fuseki."""
    cfg = FusekiConfig()
    cfg.uri = None  # type: ignore[assignment]
    cfg.auth = None  # type: ignore[assignment]
    return cfg


def build_ontocast_config(settings: PlatformSettings) -> OntoCastConfig:
    """Build an OntoCast ``Config`` from our ``PlatformSettings``.

    Phase 0 behavior:
    - LLM/Chunk/Aggregation/WebSearch sections come from their own env vars
      via OntoCast's ``BaseSettings`` defaults. We do NOT touch them.
    - Paths are overridden so the OntoCast working directory always matches
      ``PlatformSettings.working_directory``.
    - Neo4j and Fuseki are forcibly disabled regardless of NEO4J_*/FUSEKI_*
      env vars in the shell. They will be wired in Phase 4.
    """
    # Start from defaults that pull in any LLM_*/CHUNK_*/AGG_* env vars
    # via each section's own SettingsConfigDict.
    tool_cfg = ToolConfig()

    # Override paths from the platform settings.
    tool_cfg.path_config = PathConfig(
        working_directory=settings.working_directory,
        ontology_directory=settings.ontology_directory,
    )

    # Phase 0: forcibly disable non-filesystem backends.
    if settings.storage_backend == "filesystem":
        tool_cfg.neo4j = _empty_neo4j_config()
        tool_cfg.fuseki = _empty_fuseki_config()
    # (No 'else' here yet — Phase 4 will add the fuseki/neo4j branches.)

    cfg = OntoCastConfig(tool_config=tool_cfg)

    # Validate LLM config eagerly so misconfiguration surfaces at startup,
    # not on the first /process call.
    try:
        cfg.validate_llm_config()
    except ValueError as exc:
        # Re-raise with a hint about where to set the variable. OntoCast's
        # error already mentions the env var name; we add the file location.
        raise ValueError(f"{exc} (set it in `.env` or your shell environment)") from exc

    return cfg


def load_settings() -> PlatformSettings:
    """Load `PlatformSettings` from the environment.

    Separated from module-level instantiation so tests can swap env vars
    via ``monkeypatch`` without import-time side effects.
    """
    return PlatformSettings()  # type: ignore[call-arg]


# Provider-grade LLM/embedding config helpers can be added in later phases.
# For Phase 0, OntoCast's own ``LLMConfig`` is sufficient.
__all__ = [
    "Phase",
    "PlatformSettings",
    "StorageBackend",
    "build_ontocast_config",
    "load_settings",
    "LLMConfig",
]