algoriq 0.2.0__py3-none-any.whl

algoriq/__init__.py

@@ -0,0 +1,71 @@
+"""``import algoriq as aq`` — 공개 배포물의 진입점.
+
+이 파일은 **wheel 에만 실린다.** 소스 트리의 ``packages/algoriq/src/algoriq/`` 에는
+``__init__.py`` 가 없고(PEP 420 암묵 네임스페이스), 그 부재는 12 서비스가 의존하는 성질이라
+건드리지 않는다. 그래서 여기 따로 저작해 빌드 훅이 아카이브 경로 ``algoriq/__init__.py`` 로
+force-include 한다 — 레포 안에서는 존재하지 않고 사용자 디스크에서만 존재한다.
+
+## 왜 있나
+
+``pip install algoriq`` 를 한 사람이 다음 줄에 쓰는 것이 ``import algoriq`` 다. 그것이
+계산을 주지 않으면 배포물 이름과 임포트 이름이 갈려 있다는 뜻이고, 그 갈림은 설치 직후
+첫 줄에서 드러난다. 실제 API 는 ``algoriq_research`` 에 살고 앞으로도 거기 산다(그 이름이
+SDK 의 임포트 루트이고, 배포물명만 인덱스에서 이름을 다툰다) — 여기서는 그리로 위임한다.
+
+## 왜 지연인가
+
+``algoriq_research`` 를 여기서 즉시 임포트하면 ``import algoriq.schemas.strategy`` 한 줄이
+numpy·pandas·scipy 를 끌고 온다. PEP 562 ``__getattr__`` 는 **이름을 실제로 집을 때까지**
+그 비용을 미룬다 — ``aq.deflated_sharpe_ratio`` 를 쓰는 사람만 그 값을 낸다.
+
+## ``pkgutil.extend_path`` 가 하는 일
+
+``__init__.py`` 가 생기는 순간 ``algoriq`` 는 암묵 네임스페이스에서 **정규 패키지**가 되고,
+정규 패키지의 ``__path__`` 는 자기 디렉터리 하나다. 두 배포물이 같은 ``site-packages`` 로
+풀리는 보통의 설치에서는 그 하나에 모든 파일이 있어 아무 문제가 없다(독립 측정 3회). 갈리는
+것은 **서로 다른 ``sys.path`` 엔트리에 앉을 때**뿐이고 — editable 과 wheel 이 섞인 이 레포의
+개발 환경이 정확히 그 형상이다 — ``extend_path`` 가 ``sys.path`` 를 훑어 같은 이름의
+디렉터리를 ``__path__`` 에 합쳐 그 경우까지 덮는다. 없어도 대부분 동작한다는 것이 이 줄을
+빼면 안 되는 이유다: 깨지는 환경이 드물어서 **깨진 채로 오래 간다.**
+"""
+
+from __future__ import annotations
+
+import pkgutil
+from typing import Any
+
+#: 같은 이름의 다른 ``sys.path`` 엔트리를 합친다. 모듈 docstring 참조.
+__path__ = pkgutil.extend_path(__path__, __name__)
+
+#: 위임 대상. 문자열로 두어 이 모듈이 임포트될 때 따라 들어오지 않게 한다.
+_DELEGATE = "algoriq_research"
+
+
+def __getattr__(name: str) -> Any:
+    """``algoriq_research`` 의 공개 이름을 여기서도 집게 한다.
+
+    Args:
+        name: 집으려는 속성 이름.
+
+    Returns:
+        ``algoriq_research`` 가 그 이름으로 내놓는 객체.
+
+    Raises:
+        AttributeError: 그쪽에도 없는 이름일 때. ⛔ 메시지를 ``algoriq_research`` 것으로
+            두지 않고 다시 쓴다 — 사용자는 ``algoriq`` 를 임포트했고, 자기가 쓴 적 없는
+            이름이 오류에 나오면 그것부터 찾아 나선다.
+    """
+    import importlib
+
+    delegate = importlib.import_module(_DELEGATE)
+    try:
+        return getattr(delegate, name)
+    except AttributeError:
+        raise AttributeError(f"module 'algoriq' has no attribute {name!r}") from None
+
+
+def __dir__() -> list[str]:
+    """``dir(algoriq)`` 와 탭 완성이 실제 표면을 보이게 한다."""
+    import importlib
+
+    return sorted(set(dir(importlib.import_module(_DELEGATE))) | set(globals()))

algoriq/core/__init__.py

@@ -0,0 +1,154 @@
+"""algoriq.core — Cross-service infrastructure SSOT for AlgoriQ backend services.
+
+Package structure:
+    algoriq.core.logging           — structlog-based structured logging (setup_logging)
+    algoriq.core.internal_auth     — InternalAuthMiddleware + HMAC helpers
+    algoriq.core.correlation       — cross-hop correlation id (header, contextvar, ASGI)
+    algoriq.core.base_config       — BaseAlgoriqSettings (pydantic-settings)
+    algoriq.core.service_topology  — the one service-coordinate registry
+
+Why every top-level re-export is lazy (PEP 562)
+-----------------------------------------------
+The names below are the canonical public API: ``from algoriq.core import
+setup_logging`` and ``from algoriq.core.logging import setup_logging`` are
+interchangeable, and that stays true. What changed is *when* each submodule is
+executed.
+
+Importing **any** ``algoriq.core`` submodule runs this file first. When this
+file imported its submodules eagerly, that made the whole server stack a
+transitive dependency of a pure data table: ``algoriq.schemas.constants`` reads
+``algoriq.core.service_topology`` for one coordinate registry, and so
+``import algoriq.ml.covariance`` loaded ``fastapi`` (via ``core.dependencies``),
+``starlette`` (via ``core.celery_observability`` → ``core.correlation``),
+``pymongo`` (via ``core.platform_events``) and 2,399 modules in total — for a
+covariance estimator that needs numpy, pandas, scipy and sklearn.
+
+That blocks the notebook SDK, whose compute modules ship to Colab where no web
+framework and no Mongo driver exist. A deferral limited to "the submodules that
+look server-ish today" would encode a classification that decays the first time
+a quiet submodule grows a heavy dependency, so the deferral is uniform: this
+file executes no submodule at import time at all.
+
+The guard against silent regression is ``scripts/measure_sdk_import_boundary.py``,
+which imports each notebook compute module in its own interpreter and fails when
+a server-only distribution appears. Neither pyright nor ruff can see this
+invariant — an eager ``from algoriq.core.platform_events import …`` added here
+would type-check and lint clean while re-coupling the SDK to the server stack.
+
+Resolution failure raises. A missing submodule surfaces as the real
+``ImportError`` and an unknown name as ``AttributeError``; there is no default
+value and no swallowed import error.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Static-only bindings for the names the PEP 562 ``__getattr__`` below
+    # resolves at runtime. Type checkers and IDEs keep seeing the real objects
+    # (no ``Any`` leak, no stub class); the interpreter never runs this block.
+    from algoriq.core.base_config import BaseAlgoriqSettings
+    from algoriq.core.celery_observability import (
+        CELERY_SHUTDOWN_CONF,
+        TaskFailureEvent,
+        install_correlation_propagation,
+        install_task_failure_logging,
+        install_worker_shutdown_contract,
+        platform_event_sink,
+        revoke_run_task,
+        termination_requested_during_task,
+    )
+    from algoriq.core.cpu_budget import CpuBudget, activate_cpu_budget, resolve_cpu_budget
+    from algoriq.core.dependencies import get_user_tier, require_user_id
+    from algoriq.core.logging import CELERY_LOGGING_CONF, setup_logging
+    from algoriq.core.platform_events import emit_platform_event_sync, upsert_platform_event_sync
+    from algoriq.core.sweeper_watchdog import HeartbeatVerdict, check_sweeper_heartbeat
+    from algoriq.core.urls import build_mongodb_uri, build_postgres_uri, build_redis_url
+
+__version__ = "0.1.0"
+
+#: Public name → owning submodule. This is the whole re-export surface; a name
+#: absent here is absent from the package, which is what keeps ``__all__`` and
+#: the runtime hook from drifting apart (``test_core_lazy_exports.py`` pins it).
+_LAZY_EXPORTS: dict[str, str] = {
+    "BaseAlgoriqSettings": "algoriq.core.base_config",
+    "CELERY_SHUTDOWN_CONF": "algoriq.core.celery_observability",
+    "TaskFailureEvent": "algoriq.core.celery_observability",
+    "install_correlation_propagation": "algoriq.core.celery_observability",
+    "install_task_failure_logging": "algoriq.core.celery_observability",
+    "install_worker_shutdown_contract": "algoriq.core.celery_observability",
+    "platform_event_sink": "algoriq.core.celery_observability",
+    "revoke_run_task": "algoriq.core.celery_observability",
+    "termination_requested_during_task": "algoriq.core.celery_observability",
+    "CpuBudget": "algoriq.core.cpu_budget",
+    "activate_cpu_budget": "algoriq.core.cpu_budget",
+    "resolve_cpu_budget": "algoriq.core.cpu_budget",
+    "get_user_tier": "algoriq.core.dependencies",
+    "require_user_id": "algoriq.core.dependencies",
+    "CELERY_LOGGING_CONF": "algoriq.core.logging",
+    "setup_logging": "algoriq.core.logging",
+    "emit_platform_event_sync": "algoriq.core.platform_events",
+    "upsert_platform_event_sync": "algoriq.core.platform_events",
+    "HeartbeatVerdict": "algoriq.core.sweeper_watchdog",
+    "check_sweeper_heartbeat": "algoriq.core.sweeper_watchdog",
+    "build_mongodb_uri": "algoriq.core.urls",
+    "build_postgres_uri": "algoriq.core.urls",
+    "build_redis_url": "algoriq.core.urls",
+}
+
+__all__ = [
+    "CELERY_LOGGING_CONF",
+    "CELERY_SHUTDOWN_CONF",
+    "BaseAlgoriqSettings",
+    "CpuBudget",
+    "HeartbeatVerdict",
+    "TaskFailureEvent",
+    "activate_cpu_budget",
+    "build_mongodb_uri",
+    "build_postgres_uri",
+    "build_redis_url",
+    "check_sweeper_heartbeat",
+    "emit_platform_event_sync",
+    "get_user_tier",
+    "install_correlation_propagation",
+    "install_task_failure_logging",
+    "install_worker_shutdown_contract",
+    "platform_event_sink",
+    "require_user_id",
+    "resolve_cpu_budget",
+    "revoke_run_task",
+    "setup_logging",
+    "termination_requested_during_task",
+    "upsert_platform_event_sync",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Resolve a lazily re-exported ``algoriq.core`` name (PEP 562).
+
+    Args:
+        name: Attribute requested on the ``algoriq.core`` package.
+
+    Returns:
+        The resolved object, also cached into the module globals so subsequent
+        lookups skip this hook entirely.
+
+    Raises:
+        AttributeError: If ``name`` is not part of the re-export surface —
+            standard package behaviour for an unknown attribute.
+        ImportError: Propagated unchanged when the owning submodule fails to
+            import. A deferred import that cannot be satisfied is a real
+            failure, not a missing attribute.
+    """
+    module_path = _LAZY_EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    value = getattr(importlib.import_module(module_path), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Keep the lazily re-exported names visible to ``dir()`` / tab completion."""
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))

algoriq/core/service_topology.py

@@ -0,0 +1,256 @@
+"""service_topology — one coordinate registry for the pipeline services (#2034 S2 · D5).
+
+Why one table instead of many maps
+----------------------------------
+A map keyed on service and *named after its key* says nothing about its
+*codomain*, so ``grep`` cannot tell the MinIO object-key token from the HTTP path
+token — and the two genuinely differ (``strategy`` is ``"strategy"`` on storage
+but ``"strategies"`` on HTTP). That shape also duplicates silently: nine such
+maps sat in six modules (``SERVICE_SEGMENT_MAP``, ``SERVICE_PREFIX_MAP``,
+``SERVICE_RUN_ID_FIELD``, ``_SERVICE_TO_CLIENT_CLS``, ``_SERVICE_TO_ENV_KEYS``,
+``_DEFAULT_SERVICE_URLS``, ``_SEGMENTS``, ``MCP_SERVICE_TYPE_TO_CLIENT``,
+``_DETAIL_IDENTITY_KEY``), two of them byte-identical copies of the same
+client map, and the ninth was found only because the enforcement gate below was
+written.
+
+The fix is not a naming rule — a rule cannot stop a tenth map. Every coordinate
+of a service is one field on one record here, and the historical maps become
+one-line comprehensions over this table. A new coordinate is a new *field*,
+which is a declaration everyone reviewing the record sees, and
+``packages/algoriq/tests/core/test_service_topology_gate.py`` fails on any
+service-keyed dict literal declared outside this module.
+
+Why the values are not derived from the service name
+----------------------------------------------------
+They are not derivable. ``feature``'s object-key segment is ``"features"``
+while ``curation``'s is ``"curation"``; #1834 is the live evidence of what
+guessing costs (a lineage walk that resolved to a prefix no object ever had).
+The table is explicit on purpose and its values are frozen: a field here is a
+coordinate that some other layer already stamped into storage or a URL.
+
+Axis boundaries
+---------------
+* :data:`SERVICE_TOPOLOGY` — the five services on the run chain. Every field is
+  populated for every row; a partial row would put ``None`` handling into
+  every derived view.
+* :data:`NON_PIPELINE_ARTIFACT_NAMESPACES` — oracle. It owns an artifact-id
+  prefix (``or_``) and a storage segment, and lineage walks resolve it, but it
+  mints no chain run and has no per-service run client, so it is not a
+  :data:`ServiceId`. Its prefix is **not** ``None``: ``ORACLE_ARTIFACT_ID_PREFIX``
+  is live in ``services/oracle/src/pipeline/oracle_report_producer.py`` and that
+  module asserts the round-trip against the manifest-chain SSOT at produce time.
+* :data:`NON_SERVICE_RUN_ID_NAMESPACES` — ``opt``, the oracle optimisation
+  job-id namespace. It mints ids through ``generate_run_id`` but is not a
+  service: it can be neither a ``manifest.service`` value nor a path segment.
+  Declaring it as its own namespace lets the type say that, instead of a bare
+  entry in a service-keyed map that a comment has to explain away.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, NamedTuple, get_args
+
+#: The five services that own a run surface, in pipeline order.
+#:
+#: The name is ``ServiceId`` rather than a *type* name because the value set is the
+#: set of services and the service name already says which service it is.
+#: ``apps/web/src/lib/serviceRouter.ts``
+#: ``SERVICE_IDS`` is the cross-language mirror and
+#: ``packages/algoriq/tests/tools/test_service_id_ssot.py`` locks the two together.
+ServiceId = Literal["curation", "feature", "strategy", "validation", "portfolio"]
+
+
+class ServiceCoords(NamedTuple):
+    """Every coordinate a caller can need for one pipeline service.
+
+    Attributes:
+        run_id_prefix: Run-ID prefix without the underscore (``"cur"`` →
+            ``cur_0001``). ``generate_run_id`` mints it; ``resolve_service_from_run_id``
+            routes on it.
+        object_key_segment: MinIO object-key segment —
+            ``{owner}/{segment}/{artifact_id}/``. **Not** the HTTP segment.
+        http_path_segment: Plural URL segment of the service API
+            (``/api/v1/{segment}/...``). **Not** the storage segment.
+        run_id_field: The key a run **list item** carries its own run id under.
+            The services never agreed on one name: curation uses the generic
+            ``run_id``, everyone else prefixes it. Reading the wrong key returns
+            ``""`` rather than raising (#1961).
+        detail_identity_key: The key a run **detail** body carries its identity
+            under. Deliberately a separate coordinate from ``run_id_field``: the
+            two disagree for four of the five services (a strategy detail body
+            says ``run_id`` while its list item says ``strategy_run_id``), and
+            reading the wrong one yields ``None`` — the exact absence the MCP
+            read path must not swallow, which is why it is resolved per service
+            rather than ``or``-chained across both spellings.
+        client_env_keys: Environment variables holding this service's base URL,
+            in resolution order. advisor and mcp-gateway historically spelled
+            some of these differently, hence a tuple rather than one name.
+        default_base_url: Compose-network fallback when no env var is set.
+        model_type_detail_path: Key path, inside the run **detail** body, to the
+            model type the run trained. Empty for every service whose run spec
+            declares no ``model_type`` field — an absence of the axis, not a
+            lookup that fails, so a reader branches on the empty path instead of
+            probing and interpreting a miss. Only ``strategy`` declares one.
+
+            The strategy path is nested because a *top-level* ``model_type``
+            cannot exist on ``strategyRuns``: ``StrategyRunDocument`` is
+            ``extra="forbid"`` with a derived DB-level ``$jsonSchema`` validator,
+            so the collection has no room for the key and reading one is answered
+            by absence on every document (#2287 D-6). ``spec.model_type`` is
+            required by ``StrategyRunSpec`` and is written when the run document
+            is created, before any work runs — a run that failed in its first
+            120 ms still carries it.
+
+            ⚠️ The detail body also carries ``lineage.model_type``. That is a
+            different axis (lineage metadata, populated by the lineage
+            publisher), and reading it here is how a model identity silently
+            becomes ``null``. This path is the one the owning service reads.
+    """
+
+    run_id_prefix: str
+    object_key_segment: str
+    http_path_segment: str
+    run_id_field: str
+    detail_identity_key: str
+    client_env_keys: tuple[str, ...]
+    default_base_url: str
+    model_type_detail_path: tuple[str, ...]
+
+
+SERVICE_TOPOLOGY: dict[ServiceId, ServiceCoords] = {
+    "curation": ServiceCoords(
+        run_id_prefix="cur",
+        object_key_segment="curation",
+        http_path_segment="curations",
+        run_id_field="run_id",
+        detail_identity_key="run_id",
+        client_env_keys=("CURATION_API_URL",),
+        default_base_url="http://svc-curation:8000",
+        model_type_detail_path=(),
+    ),
+    "feature": ServiceCoords(
+        run_id_prefix="feat",
+        # Non-identity with the service name, and deliberately so: prod holds 149
+        # objects under ``features/``. #1834 fixed the walker to read this table
+        # instead of re-deriving the segment from the name; identity-ising it here
+        # would revert that fix.
+        object_key_segment="features",
+        http_path_segment="features",
+        run_id_field="feature_run_id",
+        detail_identity_key="run_id",
+        client_env_keys=("FEATURE_API_URL",),
+        default_base_url="http://svc-feature:8000",
+        model_type_detail_path=(),
+    ),
+    "strategy": ServiceCoords(
+        run_id_prefix="strat",
+        object_key_segment="strategy",
+        http_path_segment="strategies",
+        run_id_field="strategy_run_id",
+        detail_identity_key="run_id",
+        client_env_keys=("STRATEGY_API_URL",),
+        default_base_url="http://svc-strategy:8000",
+        model_type_detail_path=("spec", "model_type"),
+    ),
+    "validation": ServiceCoords(
+        run_id_prefix="val",
+        object_key_segment="validation",
+        http_path_segment="validations",
+        run_id_field="validation_run_id",
+        detail_identity_key="run_id",
+        client_env_keys=("VALIDATION_API_URL",),
+        default_base_url="http://svc-validation:8000",
+        model_type_detail_path=(),
+    ),
+    "portfolio": ServiceCoords(
+        run_id_prefix="port",
+        object_key_segment="portfolio",
+        http_path_segment="portfolios",
+        run_id_field="portfolio_run_id",
+        detail_identity_key="portfolio_run_id",
+        client_env_keys=("PORTFOLIO_API_URL",),
+        default_base_url="http://svc-portfolio:8000",
+        model_type_detail_path=(),
+    ),
+}
+
+
+class ArtifactNamespace(NamedTuple):
+    """A producer that owns artifact coordinates without being on the run chain.
+
+    Attributes:
+        artifact_id_prefix: Artifact-id prefix without the underscore.
+        object_key_segment: MinIO object-key segment for its artifacts.
+    """
+
+    artifact_id_prefix: str
+    object_key_segment: str
+
+
+#: Producers with artifact coordinates but no chain run. Lineage walks resolve
+#: their ids, so their prefix and segment must be declared here rather than
+#: hardcoded at each walker (``manifest_chain`` carried a hardcoded ``"or_"``
+#: entry directly under a comment recording the #1179 incident caused by exactly
+#: that kind of hardcoding).
+NON_PIPELINE_ARTIFACT_NAMESPACES: dict[str, ArtifactNamespace] = {
+    "oracle": ArtifactNamespace(artifact_id_prefix="or", object_key_segment="oracle"),
+}
+
+#: Run-ID namespaces that are not a service at all. ``opt`` is the oracle
+#: optimisation job-id namespace: it mints ids but can never be a ``manifest.service``
+#: value or a path segment, which is why it is declared apart from the two maps
+#: above instead of sitting inside them behind a comment.
+NON_SERVICE_RUN_ID_NAMESPACES: dict[str, str] = {"opt": "opt"}
+
+
+# ---------------------------------------------------------------------------
+# Import-time completeness guard
+# ---------------------------------------------------------------------------
+# Rewritten from the ``manifest_chain`` guard it replaces (#2034 D5-c): that
+# guard checked two maps against each other, and those two maps are now one
+# record, so the drift it watched for is structurally impossible. What is still
+# possible is a row missing from this table, or a namespace colliding with a
+# service — both of which would surface deep inside a write path, so they fail
+# the import instead.
+
+_MISSING_ROWS: list[str] = sorted(set(get_args(ServiceId)) - set(SERVICE_TOPOLOGY))
+if _MISSING_ROWS:  # pragma: no cover — import-time structural guard.
+    raise RuntimeError(
+        f"service_topology: ServiceId members with no SERVICE_TOPOLOGY row: {_MISSING_ROWS}. "
+        "Every service must declare all of its coordinates before any derived view can "
+        "be total."
+    )
+
+_COLLIDING_NAMESPACES: list[str] = sorted(
+    (set(NON_PIPELINE_ARTIFACT_NAMESPACES) | set(NON_SERVICE_RUN_ID_NAMESPACES))
+    & set(SERVICE_TOPOLOGY)
+)
+if _COLLIDING_NAMESPACES:  # pragma: no cover — import-time structural guard.
+    raise RuntimeError(
+        f"service_topology: namespaces collide with a ServiceId: {_COLLIDING_NAMESPACES}. "
+        "A colliding key would silently overwrite the service's entry in the derived "
+        "prefix/segment maps."
+    )
+
+_ALL_PREFIXES: list[str] = [coords.run_id_prefix for coords in SERVICE_TOPOLOGY.values()] + [
+    namespace.artifact_id_prefix for namespace in NON_PIPELINE_ARTIFACT_NAMESPACES.values()
+]
+_DUPLICATE_PREFIXES: list[str] = sorted(
+    {prefix for prefix in _ALL_PREFIXES if _ALL_PREFIXES.count(prefix) > 1}
+)
+if _DUPLICATE_PREFIXES:  # pragma: no cover — import-time structural guard.
+    raise RuntimeError(
+        f"service_topology: duplicate run/artifact id prefixes: {_DUPLICATE_PREFIXES}. "
+        "Prefix resolution is first-match, so a duplicate routes one service's runs to "
+        "another service's storage."
+    )
+
+
+__all__ = [
+    "NON_PIPELINE_ARTIFACT_NAMESPACES",
+    "NON_SERVICE_RUN_ID_NAMESPACES",
+    "SERVICE_TOPOLOGY",
+    "ArtifactNamespace",
+    "ServiceCoords",
+    "ServiceId",
+]