ontology

ontology_platform/platform/config.py

@@ -0,0 +1,222 @@
+"""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",
+]