ygo74-agent-runtime 0.0.2__tar.gz

ygo74_agent_runtime-0.0.2/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: ygo74-agent-runtime
+Version: 0.0.2
+Summary: Cross-language AI enterprise agent runtime
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: PyJWT>=2.8

ygo74_agent_runtime-0.0.2/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ygo74-agent-runtime"
+version = "0.0.2"
+description = "Cross-language AI enterprise agent runtime"
+requires-python = ">=3.11"
+dependencies = [
+  "pydantic>=2.7",
+  "typing-extensions>=4.12",
+  "PyJWT>=2.8"
+]

ygo74_agent_runtime-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ygo74_agent_runtime-0.0.2/ygo74/agent_runtime/__init__.py

@@ -0,0 +1,105 @@
+from ygo74.agent_runtime.domains.contracts.exchange_models import StandardExchangeRequest, StandardExchangeResponse
+from ygo74.agent_runtime.domains.contracts.error_envelope import ErrorEnvelope
+from ygo74.agent_runtime.domains.auth.auth_context import AuthenticatedUserContext, ResolvedUser, UserIdentity
+from ygo74.agent_runtime.domains.auth.auth_errors import AuthenticationError, AuthorizationError
+from ygo74.agent_runtime.domains.auth.authenticator import Authenticator, RequestAuthenticator
+from ygo74.agent_runtime.domains.auth.apikey_authenticator import (
+    ApiKeyAuthenticator,
+    ApiKeyUserResolver,
+    StaticApiKeyUserResolver,
+)
+from ygo74.agent_runtime.domains.auth.jwt_authenticator import JwtAuthenticator, JwtValidationConfig
+from ygo74.agent_runtime.domains.discovery.agent_descriptor import (
+    AgentCapabilitySet,
+    AgentDescriptor,
+    AgentSkill,
+    CapabilitySizeUnit,
+    DiscoveryVisibility,
+    Modality,
+)
+from ygo74.agent_runtime.domains.discovery.agent_access_policy import AgentAccessPolicy, RoleRequiredAccessPolicy
+from ygo74.agent_runtime.domains.discovery.anthropic_model_projection import AnthropicModelProjection
+from ygo74.agent_runtime.domains.discovery.capability_extensions import CapabilityExtensions
+from ygo74.agent_runtime.domains.discovery.capability_validator import CapabilityValidator
+from ygo74.agent_runtime.domains.discovery.descriptor_binding import DescriptorBinding
+from ygo74.agent_runtime.domains.discovery.descriptor_defaults import DescriptorDefaults
+from ygo74.agent_runtime.domains.discovery.descriptor_registry import DescriptorOrdering, DescriptorRegistry
+from ygo74.agent_runtime.domains.discovery.dialect_selector import (
+    DialectSelection,
+    DialectSelector,
+    ProviderDialect,
+)
+from ygo74.agent_runtime.domains.discovery.discovery_configuration import (
+    DiscoveryConfiguration,
+    DiscoveryService,
+    DiscoverySurface,
+)
+from ygo74.agent_runtime.domains.discovery.discovery_errors import (
+    DiscoveryError,
+    DiscoveryErrorCategory,
+    DiscoveryErrorCode,
+    DiscoveryErrors,
+)
+from ygo74.agent_runtime.domains.discovery.model_route_resolver import ModelRouteResolver
+from ygo74.agent_runtime.domains.discovery.openai_model_projection import OpenAiModelProjection
+from ygo74.agent_runtime.domains.discovery.pagination import (
+    DiscoveryPagination,
+    PaginationRequest,
+    PaginationResult,
+)
+from ygo74.agent_runtime.domains.endpoints.fastapi_endpoints import (
+    add_ai_endpoint,
+    add_ai_endpoints,
+    add_discovery_endpoints,
+)
+
+__all__ = [
+    "StandardExchangeRequest",
+    "StandardExchangeResponse",
+    "ErrorEnvelope",
+    "AuthenticatedUserContext",
+    "UserIdentity",
+    "ResolvedUser",
+    "AuthenticationError",
+    "AuthorizationError",
+    "Authenticator",
+    "RequestAuthenticator",
+    "JwtAuthenticator",
+    "JwtValidationConfig",
+    "ApiKeyAuthenticator",
+    "ApiKeyUserResolver",
+    "StaticApiKeyUserResolver",
+    "AgentDescriptor",
+    "AgentCapabilitySet",
+    "AgentSkill",
+    "CapabilitySizeUnit",
+    "DiscoveryVisibility",
+    "Modality",
+    "AgentAccessPolicy",
+    "RoleRequiredAccessPolicy",
+    "DescriptorRegistry",
+    "DescriptorOrdering",
+    "DescriptorDefaults",
+    "DescriptorBinding",
+    "CapabilityValidator",
+    "CapabilityExtensions",
+    "DiscoveryConfiguration",
+    "DiscoveryService",
+    "DiscoverySurface",
+    "DiscoveryError",
+    "DiscoveryErrorCategory",
+    "DiscoveryErrorCode",
+    "DiscoveryErrors",
+    "DialectSelection",
+    "DialectSelector",
+    "ProviderDialect",
+    "DiscoveryPagination",
+    "ModelRouteResolver",
+    "PaginationRequest",
+    "PaginationResult",
+    "OpenAiModelProjection",
+    "AnthropicModelProjection",
+    "add_ai_endpoint",
+    "add_ai_endpoints",
+    "add_discovery_endpoints",
+]

ygo74_agent_runtime-0.0.2/ygo74/agent_runtime/domains/auth/apikey_authenticator.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Protocol
+
+from ygo74.agent_runtime.domains.auth.auth_context import AuthenticatedUserContext, ResolvedUser
+from ygo74.agent_runtime.domains.auth.auth_errors import AuthenticationError
+
+
+class ApiKeyUserResolver(Protocol):
+    """Contract a developer implements to map an API key to a user.
+
+    Returning ``None`` means the key is unknown and the request is rejected with
+    ``api_key_invalid``. The returned :class:`ResolvedUser` defines exactly which
+    user information is loaded into the handler's ``auth_context``.
+    """
+
+    def resolve_user(self, api_key: str) -> ResolvedUser | None:
+        ...
+
+
+@dataclass(slots=True)
+class StaticApiKeyUserResolver:
+    """In-memory resolver, mostly useful for local development and tests."""
+
+    users_by_key: dict[str, ResolvedUser]
+
+    def resolve_user(self, api_key: str) -> ResolvedUser | None:
+        return self.users_by_key.get(api_key)
+
+
+class ApiKeyAuthenticator:
+    """Authenticates callers presenting an API key header.
+
+    The raw key is never propagated into the resulting context: only the user
+    information returned by the resolver is exposed to the handler.
+    """
+
+    DEFAULT_HEADER_NAME = "x-api-key"
+
+    def __init__(self, resolver: ApiKeyUserResolver, *, header_name: str = DEFAULT_HEADER_NAME) -> None:
+        self._resolver = resolver
+        self._header_name = header_name.lower()
+
+    @property
+    def auth_type(self) -> str:
+        return "api_key"
+
+    @property
+    def header_name(self) -> str:
+        return self._header_name
+
+    def can_authenticate(self, headers: Mapping[str, Any]) -> bool:
+        return bool(headers.get(self._header_name))
+
+    def missing_credential_error(self) -> AuthenticationError:
+        return AuthenticationError(
+            code="api_key_header_missing",
+            message=f"Missing {self._header_name} header",
+        )
+
+    def authenticate(self, headers: Mapping[str, Any]) -> AuthenticatedUserContext:
+        api_key = headers.get(self._header_name)
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise self.missing_credential_error()
+
+        return self.authenticate_key(api_key)
+
+    def authenticate_key(self, api_key: str) -> AuthenticatedUserContext:
+        if not api_key:
+            raise self.missing_credential_error()
+
+        user = self._resolve(api_key)
+
+        return AuthenticatedUserContext(
+            auth_type=self.auth_type,
+            identity=user.to_identity(),
+            roles=list(user.roles),
+            groups=list(user.groups),
+            scopes=list(user.scopes),
+            claims=dict(user.claims),
+            tenant_id=user.tenant_id,
+        )
+
+    def _resolve(self, api_key: str) -> ResolvedUser:
+        try:
+            resolved: object = self._resolver.resolve_user(api_key)
+        except AuthenticationError:
+            raise
+        except Exception as ex:
+            raise AuthenticationError(
+                code="user_resolution_failed",
+                message="API key user-resolution hook raised an error",
+            ) from ex
+
+        if resolved is None:
+            raise AuthenticationError(code="api_key_invalid", message="API key is not recognized")
+
+        if not isinstance(resolved, ResolvedUser):
+            raise AuthenticationError(
+                code="user_context_malformed",
+                message="API key user-resolution hook must return a ResolvedUser",
+            )
+
+        if not resolved.user_id or not resolved.user_id.strip():
+            raise AuthenticationError(
+                code="user_context_malformed",
+                message="API key user-resolution hook must provide a user_id",
+            )
+
+        return resolved

ygo74_agent_runtime-0.0.2/ygo74/agent_runtime/domains/auth/auth_context.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class UserIdentity:
+    """Normalized identity of the authenticated caller."""
+
+    user_id: str
+    subject: str | None = None
+    username: str | None = None
+    name: str | None = None
+    given_name: str | None = None
+    family_name: str | None = None
+    email: str | None = None
+    email_verified: bool | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "userId": self.user_id,
+            "subject": self.subject or self.user_id,
+            "username": self.username,
+            "name": self.name,
+            "givenName": self.given_name,
+            "familyName": self.family_name,
+            "email": self.email,
+            "emailVerified": self.email_verified,
+        }
+
+
+@dataclass(slots=True)
+class ResolvedUser:
+    """Return schema of an API key user-resolution hook.
+
+    This is the contract a developer must satisfy when mapping an API key to a
+    user: whatever is populated here is what the handler will find in its
+    ``auth_context``.
+    """
+
+    user_id: str
+    username: str | None = None
+    name: str | None = None
+    given_name: str | None = None
+    family_name: str | None = None
+    email: str | None = None
+    email_verified: bool | None = None
+    roles: list[str] = field(default_factory=list)
+    groups: list[str] = field(default_factory=list)
+    scopes: list[str] = field(default_factory=list)
+    tenant_id: str | None = None
+    claims: dict[str, Any] = field(default_factory=dict)
+
+    def to_identity(self) -> UserIdentity:
+        return UserIdentity(
+            user_id=self.user_id,
+            subject=self.user_id,
+            username=self.username,
+            name=self.name,
+            given_name=self.given_name,
+            family_name=self.family_name,
+            email=self.email,
+            email_verified=self.email_verified,
+        )
+
+
+@dataclass(slots=True)
+class AuthenticatedUserContext:
+    """Normalized authentication context handed to the handler.
+
+    ``to_dict`` produces the wire shape required by the Standard Exchange
+    contract (``userId`` and ``authType`` at the top level).
+    """
+
+    auth_type: str
+    identity: UserIdentity
+    roles: list[str] = field(default_factory=list)
+    groups: list[str] = field(default_factory=list)
+    scopes: list[str] = field(default_factory=list)
+    claims: dict[str, Any] = field(default_factory=dict)
+    tenant_id: str | None = None
+
+    @property
+    def user_id(self) -> str:
+        return self.identity.user_id
+
+    def has_role(self, role: str) -> bool:
+        return role in self.roles
+
+    def has_scope(self, scope: str) -> bool:
+        return scope in self.scopes
+
+    def to_dict(self) -> dict[str, Any]:
+        context: dict[str, Any] = {
+            "authType": self.auth_type,
+            "userId": self.identity.user_id,
+            "identity": self.identity.to_dict(),
+            "roles": list(self.roles),
+            "groups": list(self.groups),
+            "scopes": list(self.scopes),
+            "claims": dict(self.claims),
+        }
+
+        if self.tenant_id is not None:
+            context["tenantId"] = self.tenant_id
+
+        return context

ygo74_agent_runtime-0.0.2/ygo74/agent_runtime/domains/auth/auth_errors.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def auth_error(code: str, message: str, category: str, details: Any | None = None) -> dict[str, Any]:
+    err: dict[str, Any] = {"code": code, "category": category, "message": message}
+    if details is not None:
+        err["details"] = details
+    return err
+
+
+@dataclass(slots=True)
+class AuthenticationError(Exception):
+    code: str
+    message: str
+    category: str = "authentication"
+    details: Any | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return auth_error(self.code, self.message, self.category, self.details)
+
+
+@dataclass(slots=True)
+class AuthorizationError(Exception):
+    """Raised by developer-owned authorization logic to deny an authenticated request.
+
+    The runtime never raises this itself: authorization decisions belong to the
+    handler. When raised, the runtime short-circuits handler execution and maps
+    it to an HTTP 403 with a structured error envelope.
+    """
+
+    code: str = "forbidden"
+    message: str = "Access denied"
+    category: str = "authorization"
+    details: Any | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return auth_error(self.code, self.message, self.category, self.details)

ygo74_agent_runtime-0.0.2/ygo74/agent_runtime/domains/auth/authenticator.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Protocol, runtime_checkable
+
+from ygo74.agent_runtime.domains.auth.auth_context import AuthenticatedUserContext
+from ygo74.agent_runtime.domains.auth.auth_errors import AuthenticationError
+
+
+@runtime_checkable
+class Authenticator(Protocol):
+    """Contract implemented by every authentication scheme.
+
+    ``RequestAuthenticator`` inspects the incoming headers and delegates to the
+    first authenticator that claims them, so adding a scheme means adding a
+    class implementing this protocol.
+    """
+
+    @property
+    def auth_type(self) -> str:
+        """Stable identifier projected as ``authContext.authType``."""
+        ...
+
+    def can_authenticate(self, headers: Mapping[str, Any]) -> bool:
+        """Return True when the request carries a credential for this scheme."""
+        ...
+
+    def authenticate(self, headers: Mapping[str, Any]) -> AuthenticatedUserContext:
+        """Validate the credential and project a normalized user context."""
+        ...
+
+    def missing_credential_error(self) -> AuthenticationError:
+        """Error raised when authentication is required but no credential was sent."""
+        ...
+
+
+@dataclass(slots=True)
+class RequestAuthenticator:
+    """Selects and runs the authenticator matching the incoming request headers.
+
+    Authenticators are evaluated in order and the first one claiming the request
+    wins, so ordering expresses precedence (JWT before API key by convention).
+    """
+
+    authenticators: list[Authenticator] = field(default_factory=list)
+    require_authentication: bool = False
+
+    def authenticate(self, headers: Mapping[str, Any] | None) -> AuthenticatedUserContext | None:
+        if headers is None:
+            if self.require_authentication:
+                raise self._missing_credential_error()
+            return None
+
+        for authenticator in self.authenticators:
+            if authenticator.can_authenticate(headers):
+                return authenticator.authenticate(headers)
+
+        if self.require_authentication:
+            raise self._missing_credential_error()
+
+        return None
+
+    def _missing_credential_error(self) -> AuthenticationError:
+        if self.authenticators:
+            return self.authenticators[0].missing_credential_error()
+
+        return AuthenticationError(
+            code="authentication_not_configured",
+            message="Authentication is required but no authenticator is configured",
+        )

ygo74_agent_runtime-0.0.2/ygo74/agent_runtime/domains/auth/claims_projection.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, cast
+
+from ygo74.agent_runtime.domains.auth.auth_context import UserIdentity
+
+_PROJECTED_CLAIM_KEYS = (
+    "iss",
+    "aud",
+    "exp",
+    "nbf",
+    "iat",
+    "jti",
+    "scope",
+    "roles",
+    "name",
+    "given_name",
+    "family_name",
+    "preferred_username",
+    "email",
+    "email_verified",
+    "groups",
+    "realm_access",
+    "resource_access",
+)
+
+
+@dataclass(slots=True)
+class ClaimsProjector:
+    """Projects raw OIDC claims into the normalized authentication context.
+
+    ``roles_claim_path`` and ``groups_claim_path`` are dot-separated paths into
+    the decoded claims (for example ``realm_access.roles`` or
+    ``resource_access.<client>.roles``), mirroring the
+    ``OPENID_REQUIRED_ROLE_PARAMETER_PATH`` style of configuration used by OIDC
+    providers such as Keycloak.
+    """
+
+    roles_claim_path: str | None = None
+    groups_claim_path: str | None = None
+
+    def identity(self, claims: Mapping[str, Any], subject: str) -> UserIdentity:
+        email_verified = claims.get("email_verified")
+
+        return UserIdentity(
+            user_id=subject,
+            subject=subject,
+            username=self._optional_str(claims.get("preferred_username")),
+            name=self._optional_str(claims.get("name")),
+            given_name=self._optional_str(claims.get("given_name")),
+            family_name=self._optional_str(claims.get("family_name")),
+            email=self._optional_str(claims.get("email")),
+            email_verified=email_verified if isinstance(email_verified, bool) else None,
+        )
+
+    def roles(self, claims: Mapping[str, Any]) -> list[str]:
+        return self.values_at(claims, self.roles_claim_path)
+
+    def groups(self, claims: Mapping[str, Any]) -> list[str]:
+        return self.values_at(claims, self.groups_claim_path)
+
+    def scopes(self, claims: Mapping[str, Any]) -> list[str]:
+        scope = claims.get("scope")
+        if isinstance(scope, str):
+            return scope.split()
+
+        return self._as_string_list(scope)
+
+    def context_claims(self, claims: Mapping[str, Any]) -> dict[str, Any]:
+        return {key: claims[key] for key in _PROJECTED_CLAIM_KEYS if key in claims}
+
+    def values_at(self, claims: Mapping[str, Any], path: str | None) -> list[str]:
+        if not path:
+            return []
+
+        return self._as_string_list(self.resolve_path(claims, path))
+
+    @staticmethod
+    def resolve_path(claims: Mapping[str, Any], path: str) -> Any:
+        value: Any = claims
+        for part in path.split("."):
+            if not isinstance(value, Mapping):
+                return None
+
+            current = cast("Mapping[str, Any]", value)
+            if part not in current:
+                return None
+
+            value = current[part]
+
+        return value
+
+    @staticmethod
+    def _as_string_list(value: Any) -> list[str]:
+        if isinstance(value, str):
+            return [value]
+
+        if isinstance(value, (list, tuple)):
+            items = cast("list[Any] | tuple[Any, ...]", value)
+            return [str(item) for item in items]
+
+        return []
+
+    @staticmethod
+    def _optional_str(value: Any) -> str | None:
+        return value if isinstance(value, str) else None