codexloop 0.1.0__py3-none-any.whl

codexloop/infrastructure/api/introspect.py

@@ -0,0 +1,248 @@
+"""Discover endpoint-backed methods on the OpenAI SDK resource class tree.
+
+Walks ``cached_property`` subresources on resource classes — no live client
+or credentials required. See architecture §15 / R11.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from dataclasses import dataclass
+from functools import cached_property
+from typing import Any
+
+import openai
+import openai.resources as resources
+from openai import OpenAI
+from openai._resource import SyncAPIResource
+
+SDK_VERSION = openai.__version__
+
+SKIP_RESOURCE_PROPS = frozenset(
+    {
+        "with_raw_response",
+        "with_streaming_response",
+        "with_options",
+        "auth_headers",
+        "default_headers",
+        "qs",
+        "copy",
+    }
+)
+SKIP_METHOD_NAMES = frozenset({"with_raw_response", "with_streaming_response"})
+
+# SDK helpers with no plain HTTP endpoint — still exposed as CLI commands but
+# enumerated explicitly so the drift gate cannot silently forget them.
+LOCAL_HELPER_PATHS = frozenset(
+    {
+        "chat.completions.parse",
+        "chat.completions.stream",
+        "responses.parse",
+        "responses.stream",
+        "beta.chat.completions.parse",
+        "beta.chat.completions.stream",
+        "beta.threads.runs.create_and_stream",
+        "beta.threads.runs.stream",
+        "beta.threads.runs.submit_tool_outputs_stream",
+        "beta.threads.create_and_run_stream",
+        "webhooks.unwrap",
+        "webhooks.verify_signature",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class EndpointSpec:
+    """One discovered SDK method under ``openai.resources``."""
+
+    resource_path: tuple[str, ...]
+    method_name: str
+    signature: str
+    is_list: bool
+    is_streaming: bool
+    path: str = ""
+    is_local_helper: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "path", ".".join((*self.resource_path, self.method_name)))
+        object.__setattr__(self, "is_local_helper", self.path in LOCAL_HELPER_PATHS)
+
+
+def _resolve_annotation_class(
+    owner_cls: type,
+    prop_name: str,
+    annotation: str,
+    *,
+    globals_ns: dict[str, Any],
+) -> type[SyncAPIResource] | None:
+    ret: Any = globals_ns.get(annotation)
+    if ret is None:
+        ret = getattr(resources, annotation, None)
+    if ret is None:
+        owner_mod = owner_cls.__module__
+        parent_pkg = owner_mod.rsplit(".", 1)[0]
+        candidates = (
+            f"openai.resources.{prop_name}",
+            f"{parent_pkg}.{prop_name}",
+            f"{parent_pkg}.{prop_name}.{prop_name}",
+            f"openai.resources.{prop_name}.{prop_name}",
+        )
+        for cand in candidates:
+            try:
+                mod = importlib.import_module(cand)
+            except ImportError:  # pragma: no cover — try next candidate
+                continue
+            if hasattr(mod, annotation):  # pragma: no branch
+                ret = getattr(mod, annotation)
+                break
+    if (
+        ret is None or not inspect.isclass(ret) or not issubclass(ret, SyncAPIResource)
+    ):  # pragma: no cover
+        return None
+    return ret
+
+
+def _resolve_subresource_class(
+    owner_cls: type,
+    prop_name: str,
+) -> type[SyncAPIResource] | None:
+    prop = None
+    for base in owner_cls.__mro__:
+        if prop_name in base.__dict__:  # pragma: no branch
+            prop = base.__dict__[prop_name]
+            break
+    if not isinstance(prop, cached_property):  # pragma: no cover
+        return None
+    ann = prop.func.__annotations__.get("return")
+    if isinstance(ann, type) and issubclass(
+        ann, SyncAPIResource
+    ):  # pragma: no cover — live type ann
+        return ann
+    if not isinstance(ann, str):  # pragma: no cover
+        return None
+    return _resolve_annotation_class(
+        owner_cls,
+        prop_name,
+        ann,
+        globals_ns=dict(prop.func.__globals__),
+    )
+
+
+def _iter_public_members(cls: type) -> list[tuple[str, Any]]:
+    """Walk SyncAPIResource MRO so empty re-export subclasses still expose methods."""
+    seen: set[str] = set()
+    members: list[tuple[str, Any]] = []
+    for base in cls.__mro__:  # pragma: no branch — SyncAPIResource always terminates walk
+        if base is SyncAPIResource or base is object:
+            break
+        if not issubclass(base, SyncAPIResource):  # pragma: no cover
+            continue
+        for name, val in base.__dict__.items():
+            if name.startswith("_") or name in seen:
+                continue
+            seen.add(name)
+            members.append((name, val))
+    return members
+
+
+def _is_streaming_name(name: str) -> bool:
+    return name == "stream" or name.endswith("_stream") or "stream" in name.split("_")
+
+
+def _walk_resource(cls: type[SyncAPIResource], prefix: tuple[str, ...]) -> list[EndpointSpec]:
+    discovered: list[EndpointSpec] = []
+    for name, val in _iter_public_members(cls):
+        if isinstance(val, cached_property):
+            if name in SKIP_RESOURCE_PROPS:  # pragma: no cover
+                continue
+            sub = _resolve_subresource_class(cls, name)
+            if sub is not None:  # pragma: no branch
+                discovered.extend(_walk_resource(sub, prefix + (name,)))
+            continue
+        if not callable(val) or isinstance(val, (classmethod, staticmethod)):  # pragma: no cover
+            continue
+        if name in SKIP_METHOD_NAMES:  # pragma: no cover
+            continue
+        try:
+            sig = inspect.signature(val)
+        except (TypeError, ValueError):  # pragma: no cover
+            continue
+        if "self" not in sig.parameters:  # pragma: no cover
+            continue
+        discovered.append(
+            EndpointSpec(
+                resource_path=prefix,
+                method_name=name,
+                signature=str(sig),
+                is_list=name == "list",
+                is_streaming=_is_streaming_name(name),
+            )
+        )
+    return discovered
+
+
+def _root_resources(
+    client_cls: type = OpenAI,
+) -> tuple[tuple[str, type[SyncAPIResource]], ...]:
+    roots: list[tuple[str, type[SyncAPIResource]]] = []
+    seen: set[str] = set()
+    for base in client_cls.__mro__:
+        for name, val in base.__dict__.items():
+            if name in seen or name.startswith("_") or name in SKIP_RESOURCE_PROPS:
+                continue
+            if not isinstance(val, cached_property):  # pragma: no cover
+                continue
+            seen.add(name)
+            sub = _resolve_subresource_class(base, name)
+            if sub is not None:  # pragma: no branch
+                roots.append((name, sub))
+    return tuple(roots)
+
+
+def discover_surface(
+    *,
+    roots: tuple[str, ...] | None = None,
+    client_cls: type = OpenAI,
+) -> tuple[EndpointSpec, ...]:
+    """Return every SDK method under the given top-level resource roots."""
+    allowed = frozenset(roots) if roots is not None else None
+    methods: list[EndpointSpec] = []
+    for root_name, root_cls in _root_resources(client_cls):
+        if allowed is not None and root_name not in allowed:
+            continue
+        methods.extend(_walk_resource(root_cls, (root_name,)))
+    return tuple(sorted(methods, key=lambda m: m.path))
+
+
+def method_by_path(methods: tuple[EndpointSpec, ...]) -> dict[str, EndpointSpec]:
+    return {m.path: m for m in methods}
+
+
+def resolve_callable(method: EndpointSpec, *, client_cls: type = OpenAI) -> Any:
+    """Resolve the unbound SDK method function for a discovered path."""
+    if not method.resource_path:
+        msg = f"empty resource path for {method.path!r}"
+        raise RuntimeError(msg)
+    cls: type[SyncAPIResource] | None = None
+    for root_name, root_cls in _root_resources(client_cls):
+        if method.resource_path[0] == root_name:
+            cls = root_cls
+            break
+    if cls is None:
+        msg = f"unknown root resource in {method.path!r}"
+        raise RuntimeError(msg)
+    for segment in method.resource_path[1:]:
+        sub = _resolve_subresource_class(cls, segment)
+        if sub is None:  # pragma: no cover — malformed EndpointSpec
+            msg = f"cannot resolve subresource {segment!r} on {cls!r}"
+            raise RuntimeError(msg)
+        cls = sub
+    for base in cls.__mro__:
+        if base is SyncAPIResource or base is object:  # pragma: no cover — always return earlier
+            break
+        fn = base.__dict__.get(method.method_name)
+        if callable(fn) and not isinstance(fn, (classmethod, staticmethod)):
+            return fn
+    msg = f"method {method.method_name!r} not found on {cls!r}"  # pragma: no cover
+    raise RuntimeError(msg)  # pragma: no cover

codexloop/infrastructure/api/json_io.py

@@ -0,0 +1,26 @@
+"""Parse ``--json`` / ``--json-file`` bodies for the generated API commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_json_payload(*, inline: str | None, json_file: Path | None) -> dict[str, Any]:
+    if inline is not None and json_file is not None:
+        msg = "pass only one of --json or --json-file, not both"
+        raise ValueError(msg)
+    if json_file is not None:
+        text = json_file.read_text(encoding="utf-8").strip()
+        if text.startswith("@"):
+            path = Path(text[1:]).expanduser()
+            text = path.read_text(encoding="utf-8")
+        inline = text
+    if inline is None:
+        return {}
+    data = json.loads(inline)
+    if not isinstance(data, dict):
+        msg = "request JSON must be an object at the top level"
+        raise TypeError(msg)
+    return data

codexloop/infrastructure/api/params.py

@@ -0,0 +1,162 @@
+"""Classify SDK method parameters for Typer / Click binding."""
+
+from __future__ import annotations
+
+import inspect
+import types
+from dataclasses import dataclass
+from typing import Any, Union, get_args, get_origin
+
+from openai import NotGiven, Omit
+
+SKIP_PARAMETERS = frozenset(
+    {
+        "self",
+        "extra_headers",
+        "extra_query",
+        "extra_body",
+    }
+)
+
+_SCALAR_BY_NAME: dict[str, type] = {
+    "int": int,
+    "float": float,
+    "str": str,
+    "bool": bool,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ScalarParam:
+    name: str
+    cli_name: str
+    annotation: Any
+    required: bool
+    default: Any
+
+
+def _is_omit_default(default: Any) -> bool:
+    return isinstance(default, (Omit, NotGiven)) or type(default).__name__ in {
+        "Omit",
+        "NotGiven",
+    }
+
+
+def _is_omit_or_not_given_type(annotation: Any) -> bool:
+    return annotation is Omit or annotation is NotGiven
+
+
+def _normalize_annotation(annotation: Any) -> Any:
+    """Reduce Optional / ``X | None`` / ``X | Omit`` forms to one type when unique.
+
+    OpenAI SDK methods are typically annotated under
+    ``from __future__ import annotations``, so runtime signatures carry *strings*
+    like ``'int | Omit'`` rather than evaluated unions.
+    """
+    if isinstance(annotation, str):
+        text = annotation.strip()
+        changed = True
+        while changed:
+            changed = False
+            if text.startswith("Optional[") and text.endswith("]"):
+                text = text[len("Optional[") : -1].strip()
+                changed = True
+                continue
+            for prefix in ("None | ", "Omit | ", "NotGiven | "):
+                if text.startswith(prefix):
+                    text = text[len(prefix) :].strip()
+                    changed = True
+                    break
+            if changed:
+                continue
+            for suffix in (" | Omit", " | NotGiven", " | None"):
+                if text.endswith(suffix):
+                    text = text[: -len(suffix)].strip()
+                    changed = True
+                    break
+        if " | " in text or "[" in text:
+            return annotation
+        return _SCALAR_BY_NAME.get(text, text)
+
+    origin = get_origin(annotation)
+    if origin is Union or isinstance(annotation, types.UnionType):
+        filtered = [
+            arg
+            for arg in get_args(annotation)
+            if arg is not type(None) and not _is_omit_or_not_given_type(arg)
+        ]
+        if len(filtered) == 1:
+            return _normalize_annotation(filtered[0])
+    return annotation
+
+
+def is_scalar_annotation(annotation: Any) -> bool:
+    if annotation is inspect.Parameter.empty:
+        return False
+    ann = _normalize_annotation(annotation)
+    if ann is bool:
+        return True
+    if ann in (int, float, str):
+        return True
+    origin = get_origin(ann)
+    if origin is not None:
+        return False
+    if isinstance(ann, str):
+        return ann in _SCALAR_BY_NAME
+    return False
+
+
+def typer_type_for_annotation(annotation: Any) -> Any:
+    """Map a (possibly stringified) scalar annotation to a Typer/Click type."""
+    ann = _normalize_annotation(annotation)
+    if ann is bool or ann == "bool":
+        return bool
+    if ann is int or ann == "int":
+        return int
+    if ann is float or ann == "float":
+        return float
+    return str
+
+
+def scalar_parameters(signature: inspect.Signature) -> tuple[ScalarParam, ...]:
+    params: list[ScalarParam] = []
+    for name, param in signature.parameters.items():
+        if name in SKIP_PARAMETERS:
+            continue
+        if not is_scalar_annotation(param.annotation):
+            continue
+        required = param.default is inspect.Parameter.empty
+        if not required and _is_omit_default(param.default):
+            required = False
+        cli_name = name.replace("_", "-")
+        params.append(
+            ScalarParam(
+                name=name,
+                cli_name=cli_name,
+                annotation=param.annotation,
+                required=required,
+                default=None if required else param.default,
+            )
+        )
+    return tuple(params)
+
+
+def build_call_kwargs(
+    signature: inspect.Signature,
+    *,
+    json_payload: dict[str, Any],
+    scalar_values: dict[str, Any],
+) -> dict[str, Any]:
+    kwargs: dict[str, Any] = dict(json_payload)
+    for name, value in scalar_values.items():
+        if value is None:
+            continue
+        kwargs[name] = value
+    for name, param in signature.parameters.items():
+        if name in SKIP_PARAMETERS or name == "self":
+            continue
+        if name in kwargs:
+            continue
+        if param.default is not inspect.Parameter.empty and not _is_omit_default(param.default):
+            kwargs[name] = param.default
+    return kwargs

codexloop/infrastructure/api/providers.py

@@ -0,0 +1,70 @@
+"""Alternate OpenAI SDK client selection for ``codexloop api --provider``."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from typing import Any
+
+from openai import AzureOpenAI, OpenAI
+
+ProviderFactory = Callable[..., Any]
+
+# Keys exposed on the CLI (--provider values use kebab-case via Typer).
+PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
+    "openai": lambda **kwargs: OpenAI(**kwargs),
+    "azure": lambda **kwargs: AzureOpenAI(**kwargs),
+    "custom": lambda **kwargs: OpenAI(**kwargs),
+}
+
+FULL_TREE_PROVIDERS = frozenset({"openai", "custom"})
+# AzureOpenAI subclasses OpenAI, so the class tree is the same; keep the set
+# explicit so a future limited Azure surface can shrink without surprise.
+AZURE_TREE_PROVIDERS = frozenset({"azure"})
+
+
+def build_client(provider: str, *, base_url: str | None = None) -> Any:
+    factory = PROVIDER_FACTORIES.get(provider)
+    if factory is None:
+        known = ", ".join(sorted(PROVIDER_FACTORIES))
+        msg = f"unknown provider {provider!r}; expected one of: {known}"
+        raise ValueError(msg)
+    kwargs: dict[str, Any] = {}
+    if base_url is not None:
+        kwargs["base_url"] = base_url
+    elif provider == "custom":
+        env_url = os.environ.get("OPENAI_BASE_URL")
+        if env_url:
+            kwargs["base_url"] = env_url
+    if provider == "azure":
+        # AzureOpenAI requires api_version; allow env defaults used by the SDK.
+        if "api_version" not in kwargs and os.environ.get("OPENAI_API_VERSION"):
+            kwargs["api_version"] = os.environ["OPENAI_API_VERSION"]
+        # Dummy key only when constructing for help/introspection paths that
+        # never call the network — real invokes still need credentials.
+        if not os.environ.get("AZURE_OPENAI_API_KEY") and not os.environ.get("OPENAI_API_KEY"):
+            kwargs.setdefault("api_key", "codexloop-azure-placeholder")
+        if not os.environ.get("AZURE_OPENAI_ENDPOINT") and "azure_endpoint" not in kwargs:
+            kwargs.setdefault("azure_endpoint", "https://example.openai.azure.com")
+        if "api_version" not in kwargs:
+            kwargs.setdefault("api_version", "2024-02-01")
+    elif not os.environ.get("OPENAI_API_KEY"):
+        kwargs.setdefault("api_key", "codexloop-placeholder")
+    return factory(**kwargs)
+
+
+def client_class_for_provider(provider: str) -> type:
+    if provider == "azure":
+        return AzureOpenAI
+    if provider in {"openai", "custom"}:
+        return OpenAI
+    msg = f"unknown provider {provider!r}"
+    raise ValueError(msg)
+
+
+def surface_roots_for_provider(provider: str) -> tuple[str, ...] | None:
+    """Return restricted roots, or ``None`` for the full OpenAI tree."""
+    if provider in FULL_TREE_PROVIDERS or provider in AZURE_TREE_PROVIDERS:
+        return None
+    msg = f"unknown provider {provider!r}"
+    raise ValueError(msg)

codexloop/infrastructure/api/registry.py

@@ -0,0 +1,13 @@
+"""Registry of generated ``codexloop api`` command paths (drift gate)."""
+
+from __future__ import annotations
+
+REGISTERED_COMMAND_PATHS: set[str] = set()
+
+
+def register_command_path(path: str) -> None:
+    REGISTERED_COMMAND_PATHS.add(path)
+
+
+def clear_registry() -> None:
+    REGISTERED_COMMAND_PATHS.clear()

codexloop/infrastructure/appserver/__init__.py

@@ -0,0 +1,6 @@
+"""Optional ``codex app-server`` JSON-RPC adapter (rate-limit enrichment)."""
+
+from codexloop.infrastructure.appserver.client import DEFAULT_ARGV, AppServerClient
+from codexloop.infrastructure.appserver.gateway import CodexAppServerGateway
+
+__all__ = ["DEFAULT_ARGV", "AppServerClient", "CodexAppServerGateway"]