pycraftcore 0.2.0__tar.gz → 0.2.2__tar.gz

{pycraftcore-0.2.0/src/pycraftcore.egg-info → pycraftcore-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycraftcore
-Version: 0.2.0
+Version: 0.2.2
 Summary: Provides reusable technical infrastructure and adapter implementations for Python applications
 Author-email: Toufik Saouchi <toufik.saouchi@gmail.com>
 License-Expression: MIT
@@ -37,43 +37,39 @@ Dynamic: license-file
 
 # pycraftcore
 
-`pycraftcore` is a reusable technical infrastructure library for Python applications: configuration loading, HTTP
-clients with retries/circuit-breaking/tracing, a pooled async SQLite repository, a sandboxed Python code runner, safe
-SQL validation, serialization, and a handful of other adapters — all built as small, swappable ports/adapters rather
-than a framework.
+`pycraftcore` is a reusable technical infrastructure library for Python applications: configuration, resilient HTTP
+clients, a pooled async SQLite repository, a sandboxed Python code runner, safe SQL validation, serialization, and a
+handful of other adapters — small, swappable building blocks rather than a framework.
 
 **Design principles:** Modularity · Reusability · Maintainability
 
-Every module follows the same shape: a `port/` package with `Protocol` interfaces and an `adapter/` package with one
-or more concrete implementations, so consumers depend on the port, not the adapter.
-
 ---
 
 ## Table of Contents
 
-- [Components](#components)
+- [Functionality](#functionality)
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Development](#development)
 
 ---
 
-## Components
+## Functionality
 
-| Module | Package | Description |
+| Module | Package | What it gives you |
 |---|---|---|
-| Configuration Management | `application_configuration` | Environment-driven YAML config (connector/operation/cronjob), `${oc.env:...}` injection, typed/validated models |
-| Authentication | `application_configuration` | Typed auth models (none / basic / token) shared across connector configs |
-| Logging | `logger` | Singleton structured logger over loguru, behind a `Logger` port |
-| Telemetry & Observability | `telemetry` | OpenTelemetry-backed tracing: span decorator, request-id enrichment, console or OTLP export |
-| HTTP Client Utilities | `http` | `aiohttp`/`httpx` clients behind a common port, retry policy, circuit breaker, and a `ResilientClient` composing all three with tracing |
-| Repository / SQLite | `repository` | Async SQLite repository backed by a real connection pool (WAL mode, `busy_timeout`) — not just an async-wrapped single connection |
-| Query Language / SQL Safety | `query_language` | `sqlglot`-based parser that rejects any non-read-only statement anywhere in the parsed tree, including nested |
-| Runtime / Sandboxed Execution | `runtime` | Runs arbitrary Python in a separate OS process with an import allowlist, memory/CPU limits, and a timeout |
-| Serialization | `serialization` | JSON, dict, and binary (msgpack) serialization for dataclasses, backed by pydantic validation |
-| Scientific computation engine | `computation` | NumPy/SciPy-backed arithmetic (log returns, rolling average/stddev) and calculus (integration, interpolation) |
-| File handler | `file_handler` | Extension-based read/write strategy (currently YAML), pluggable for more formats |
-| Profiler | `profiler` | `pyinstrument`-based async function profiling decorator |
+| Configuration Management | `application_configuration` | Environment-driven YAML configuration for connectors and operations, validated and typed |
+| Authentication | `application_configuration` | Shared auth models (none / basic / token) for any connector |
+| Logging | `logger` | Structured application logging |
+| Telemetry & Observability | `telemetry` | Distributed tracing, exportable to console or an OTLP collector |
+| HTTP Client Utilities | `http` | Resilient HTTP client with retries, circuit breaking, and tracing |
+| Repository / SQLite | `repository` | Async SQLite repository with real connection pooling for concurrent access |
+| Query Language / SQL Safety | `query_language` | Validates that a SQL statement is read-only before it reaches a database |
+| Runtime / Sandboxed Execution | `runtime` | Runs untrusted Python code in an isolated process with resource limits |
+| Serialization | `serialization` | JSON, dict, and binary (msgpack) serialization for dataclasses |
+| Scientific computation engine | `computation` | Financial arithmetic and calculus (integration, interpolation) |
+| File handler | `file_handler` | Read/write files by extension, pluggable for new formats |
+| Profiler | `profiler` | Async function profiling decorator |
 
 ---
 
@@ -134,32 +130,68 @@ connector:
       key_value: ${oc.env:connector_api_key}
 ```
 
-A database connector additionally takes `engine`, `host`, `port`, `default_name`, and a `pool` block controlling how
-many pooled connections the repository opens. An `operation/<tag>.yml` references a connector by tag and adds
-`endpoint`, `method`, and `parameters` — see `pycraftcore.application_configuration.model` for the full schema.
+**Operation example** (`operation/<tag>.yml`) — references a connector by tag:
+
+```yaml
+operation:
+  <operation_tag>:
+    name: <operation name>
+    type: api
+    connector: ${connector.<connector_tag>}
+    endpoint: /<path>
+    method: GET
+    parameters:
+      <param>: <value>
+```
+
+**Root example** (`root.yml`) — wires everything together for a given environment:
 
-**Loading it:**
+```yaml
+application_configuration:
+  env: ${oc.env:APP_ENV,debug}
+  run: async
+
+  connector:
+    api:
+      <connector_tag>: ${connector.<connector_tag>}
+    file:
+      <connector_tag>: ${connector.<connector_tag>}
+    database:
+      <connector_tag>: ${connector.<connector_tag>}
+    telemetry:
+      <connector_tag>: ${connector.<connector_tag>}
+    
+  operation:
+    <operation_tag>: ${operation.<operation_tag>}
+    # ...
+```
+
+Connectors and operations both declare a `type`, which determines which fields they take and which concrete object
+they load as.
+
+**Using it in code:**
 
 ```python
 from pathlib import Path
 
-from pycraftcore.application_configuration.adapter.load_application_configuration import (
-    LoadApplicationConfiguration,
-)
-from pycraftcore.application_configuration.adapter.omega_configuration_reader import (
-    OmegaConfigurationReader,
-)
-from pycraftcore.application_configuration.enum.run_type_environment import (
-    RunTypeEnvironment,
-)
+from pycraftcore.application_configuration.adapter.load_application_configuration import LoadApplicationConfiguration
+from pycraftcore.application_configuration.adapter.omega_configuration_reader import OmegaConfigurationReader
+from pycraftcore.application_configuration.enum.run_type_environment import RunTypeEnvironment
 from pycraftcore.logger.adapter.loguru_logger import LoguruLogger
 
 reader = OmegaConfigurationReader(RunTypeEnvironment.deploy, Path("config"))
 loader = LoadApplicationConfiguration(reader, LoguruLogger())
 
-config = loader.load()  # re-reads and validates every call; raises on failure (after logging)
+config = loader.load()
+
+connector = config.connector.api("<connector_tag>")   # ApiConnector
+operation = config.operation.api("<operation_tag>")   # ApiOperation
 ```
 
+`config.connector`/`config.operation` return the concrete connector/operation type for a given tag (`.api()`,
+`.database()`, `.file()`, `.telemetry()` where applicable) instead of a raw dict — see
+`pycraftcore.application_configuration` for the full API.
+
 ---
 
 ## Development
@@ -186,9 +218,9 @@ uv run pre-commit run --all-files --hook-stage pre-commit
 ```bash
 make install_dev   # uv sync --group dev
 make test           # uv run pytest
-make lint            # uv run ruff check 
-make format          # uv run ruff format 
-make typecheck           # uv run ty  (strict mode)
+make lint            # uv run ruff check
+make format          # uv run ruff format
+make typecheck        # uv run ty check (strict mode)
 ```
 
 Run `pytest --cov=pycraftcore --cov-report=term-missing` for a coverage breakdown by module.

{pycraftcore-0.2.0 → pycraftcore-0.2.2}/Readme.md

@@ -1,42 +1,38 @@
 # pycraftcore
 
-`pycraftcore` is a reusable technical infrastructure library for Python applications: configuration loading, HTTP
-clients with retries/circuit-breaking/tracing, a pooled async SQLite repository, a sandboxed Python code runner, safe
-SQL validation, serialization, and a handful of other adapters — all built as small, swappable ports/adapters rather
-than a framework.
+`pycraftcore` is a reusable technical infrastructure library for Python applications: configuration, resilient HTTP
+clients, a pooled async SQLite repository, a sandboxed Python code runner, safe SQL validation, serialization, and a
+handful of other adapters — small, swappable building blocks rather than a framework.
 
 **Design principles:** Modularity · Reusability · Maintainability
 
-Every module follows the same shape: a `port/` package with `Protocol` interfaces and an `adapter/` package with one
-or more concrete implementations, so consumers depend on the port, not the adapter.
-
 ---
 
 ## Table of Contents
 
-- [Components](#components)
+- [Functionality](#functionality)
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Development](#development)
 
 ---
 
-## Components
+## Functionality
 
-| Module | Package | Description |
+| Module | Package | What it gives you |
 |---|---|---|
-| Configuration Management | `application_configuration` | Environment-driven YAML config (connector/operation/cronjob), `${oc.env:...}` injection, typed/validated models |
-| Authentication | `application_configuration` | Typed auth models (none / basic / token) shared across connector configs |
-| Logging | `logger` | Singleton structured logger over loguru, behind a `Logger` port |
-| Telemetry & Observability | `telemetry` | OpenTelemetry-backed tracing: span decorator, request-id enrichment, console or OTLP export |
-| HTTP Client Utilities | `http` | `aiohttp`/`httpx` clients behind a common port, retry policy, circuit breaker, and a `ResilientClient` composing all three with tracing |
-| Repository / SQLite | `repository` | Async SQLite repository backed by a real connection pool (WAL mode, `busy_timeout`) — not just an async-wrapped single connection |
-| Query Language / SQL Safety | `query_language` | `sqlglot`-based parser that rejects any non-read-only statement anywhere in the parsed tree, including nested |
-| Runtime / Sandboxed Execution | `runtime` | Runs arbitrary Python in a separate OS process with an import allowlist, memory/CPU limits, and a timeout |
-| Serialization | `serialization` | JSON, dict, and binary (msgpack) serialization for dataclasses, backed by pydantic validation |
-| Scientific computation engine | `computation` | NumPy/SciPy-backed arithmetic (log returns, rolling average/stddev) and calculus (integration, interpolation) |
-| File handler | `file_handler` | Extension-based read/write strategy (currently YAML), pluggable for more formats |
-| Profiler | `profiler` | `pyinstrument`-based async function profiling decorator |
+| Configuration Management | `application_configuration` | Environment-driven YAML configuration for connectors and operations, validated and typed |
+| Authentication | `application_configuration` | Shared auth models (none / basic / token) for any connector |
+| Logging | `logger` | Structured application logging |
+| Telemetry & Observability | `telemetry` | Distributed tracing, exportable to console or an OTLP collector |
+| HTTP Client Utilities | `http` | Resilient HTTP client with retries, circuit breaking, and tracing |
+| Repository / SQLite | `repository` | Async SQLite repository with real connection pooling for concurrent access |
+| Query Language / SQL Safety | `query_language` | Validates that a SQL statement is read-only before it reaches a database |
+| Runtime / Sandboxed Execution | `runtime` | Runs untrusted Python code in an isolated process with resource limits |
+| Serialization | `serialization` | JSON, dict, and binary (msgpack) serialization for dataclasses |
+| Scientific computation engine | `computation` | Financial arithmetic and calculus (integration, interpolation) |
+| File handler | `file_handler` | Read/write files by extension, pluggable for new formats |
+| Profiler | `profiler` | Async function profiling decorator |
 
 ---
 
@@ -97,32 +93,68 @@ connector:
       key_value: ${oc.env:connector_api_key}
 ```
 
-A database connector additionally takes `engine`, `host`, `port`, `default_name`, and a `pool` block controlling how
-many pooled connections the repository opens. An `operation/<tag>.yml` references a connector by tag and adds
-`endpoint`, `method`, and `parameters` — see `pycraftcore.application_configuration.model` for the full schema.
+**Operation example** (`operation/<tag>.yml`) — references a connector by tag:
+
+```yaml
+operation:
+  <operation_tag>:
+    name: <operation name>
+    type: api
+    connector: ${connector.<connector_tag>}
+    endpoint: /<path>
+    method: GET
+    parameters:
+      <param>: <value>
+```
+
+**Root example** (`root.yml`) — wires everything together for a given environment:
 
-**Loading it:**
+```yaml
+application_configuration:
+  env: ${oc.env:APP_ENV,debug}
+  run: async
+
+  connector:
+    api:
+      <connector_tag>: ${connector.<connector_tag>}
+    file:
+      <connector_tag>: ${connector.<connector_tag>}
+    database:
+      <connector_tag>: ${connector.<connector_tag>}
+    telemetry:
+      <connector_tag>: ${connector.<connector_tag>}
+    
+  operation:
+    <operation_tag>: ${operation.<operation_tag>}
+    # ...
+```
+
+Connectors and operations both declare a `type`, which determines which fields they take and which concrete object
+they load as.
+
+**Using it in code:**
 
 ```python
 from pathlib import Path
 
-from pycraftcore.application_configuration.adapter.load_application_configuration import (
-    LoadApplicationConfiguration,
-)
-from pycraftcore.application_configuration.adapter.omega_configuration_reader import (
-    OmegaConfigurationReader,
-)
-from pycraftcore.application_configuration.enum.run_type_environment import (
-    RunTypeEnvironment,
-)
+from pycraftcore.application_configuration.adapter.load_application_configuration import LoadApplicationConfiguration
+from pycraftcore.application_configuration.adapter.omega_configuration_reader import OmegaConfigurationReader
+from pycraftcore.application_configuration.enum.run_type_environment import RunTypeEnvironment
 from pycraftcore.logger.adapter.loguru_logger import LoguruLogger
 
 reader = OmegaConfigurationReader(RunTypeEnvironment.deploy, Path("config"))
 loader = LoadApplicationConfiguration(reader, LoguruLogger())
 
-config = loader.load()  # re-reads and validates every call; raises on failure (after logging)
+config = loader.load()
+
+connector = config.connector.api("<connector_tag>")   # ApiConnector
+operation = config.operation.api("<operation_tag>")   # ApiOperation
 ```
 
+`config.connector`/`config.operation` return the concrete connector/operation type for a given tag (`.api()`,
+`.database()`, `.file()`, `.telemetry()` where applicable) instead of a raw dict — see
+`pycraftcore.application_configuration` for the full API.
+
 ---
 
 ## Development
@@ -149,9 +181,9 @@ uv run pre-commit run --all-files --hook-stage pre-commit
 ```bash
 make install_dev   # uv sync --group dev
 make test           # uv run pytest
-make lint            # uv run ruff check 
-make format          # uv run ruff format 
-make typecheck           # uv run ty  (strict mode)
+make lint            # uv run ruff check
+make format          # uv run ruff format
+make typecheck        # uv run ty check (strict mode)
 ```
 
 Run `pytest --cov=pycraftcore --cov-report=term-missing` for a coverage breakdown by module.

{pycraftcore-0.2.0 → pycraftcore-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pycraftcore"
-version = "0.2.0"
+version = "0.2.2"
 authors = [
     { name = "Toufik Saouchi", email = "toufik.saouchi@gmail.com" },
 ]

pycraftcore-0.2.2/src/pycraftcore/application_configuration/__init__.py

@@ -0,0 +1,17 @@
+from pycraftcore.application_configuration.model.configuration import (
+    ApplicationConfiguration,
+)
+from pycraftcore.application_configuration.model.connector import ConnectorRegistry
+from pycraftcore.application_configuration.model.operation import OperationRegistry
+from pycraftcore.application_configuration.port.configuration import Configuration
+from pycraftcore.application_configuration.port.configuration_reader import (
+    ConfigurationReader,
+)
+
+__all__ = [
+    "ApplicationConfiguration",
+    "Configuration",
+    "ConfigurationReader",
+    "ConnectorRegistry",
+    "OperationRegistry",
+]

pycraftcore-0.2.2/src/pycraftcore/application_configuration/adapter/schema.py

@@ -0,0 +1,65 @@
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Discriminator, Tag
+
+from pycraftcore.application_configuration.enum.connector_type import ConnectorType
+from pycraftcore.application_configuration.enum.run_type_application import (
+    RunTypeApplication,
+)
+from pycraftcore.application_configuration.enum.run_type_environment import (
+    RunTypeEnvironment,
+)
+from pycraftcore.application_configuration.model.configuration import (
+    ApplicationConfiguration,
+)
+from pycraftcore.application_configuration.model.connector import (
+    ApiConnector,
+    ConnectorRegistry,
+    DatabaseConnector,
+    FileConnector,
+    TelemetryConnector,
+)
+from pycraftcore.application_configuration.model.operation import (
+    ApiOperation,
+    FileOperation,
+    OperationRegistry,
+)
+
+
+def _kind_tag(value: Any) -> str:
+    """Discriminator: read `type` off a raw dict (pre-coercion) or an already-built dataclass."""
+    return value["type"] if isinstance(value, dict) else value.type.value
+
+
+_ConnectorSchemaTyping = Annotated[
+    Annotated[ApiConnector, Tag("api")]
+    | Annotated[DatabaseConnector, Tag("database")]
+    | Annotated[FileConnector, Tag("file")]
+    | Annotated[TelemetryConnector, Tag("telemetry")],
+    Discriminator(_kind_tag),
+]
+
+_OperationSchemaTyping = Annotated[
+    Annotated[ApiOperation, Tag("api")] | Annotated[FileOperation, Tag("file")],
+    Discriminator(_kind_tag),
+]
+
+
+class ApplicationConfigurationSchema(BaseModel):
+    env: RunTypeEnvironment
+    run: RunTypeApplication
+    connector: dict[ConnectorType, dict[str, _ConnectorSchemaTyping]]
+    operation: dict[str, _OperationSchemaTyping]
+
+
+class MapperDomainSchema:
+    @staticmethod
+    def map(
+        app_configuration_schema: ApplicationConfigurationSchema,
+    ) -> ApplicationConfiguration:
+        return ApplicationConfiguration(
+            env=app_configuration_schema.env,
+            run=app_configuration_schema.run,
+            connector=ConnectorRegistry(app_configuration_schema.connector),
+            operation=OperationRegistry(app_configuration_schema.operation),
+        )

{pycraftcore-0.2.0 → pycraftcore-0.2.2}/src/pycraftcore/application_configuration/enum/__init__.py

@@ -1,11 +1,13 @@
 from .connector_type import ConnectorType
 from .file_operation_action import FileOperationAction
+from .operation_type import OperationType
 from .run_type_application import RunTypeApplication
 from .run_type_environment import RunTypeEnvironment
 
 __all__ = [
     "ConnectorType",
     "FileOperationAction",
+    "OperationType",
     "RunTypeApplication",
     "RunTypeEnvironment",
 ]

pycraftcore-0.2.2/src/pycraftcore/application_configuration/enum/operation_type.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class OperationType(Enum):
+    api = "api"
+    file = "file"

{pycraftcore-0.2.0 → pycraftcore-0.2.2}/src/pycraftcore/application_configuration/model/configuration.py

@@ -1,19 +1,18 @@
 from dataclasses import dataclass
 
-from pycraftcore.application_configuration.enum.connector_type import ConnectorType
 from pycraftcore.application_configuration.enum.run_type_application import (
     RunTypeApplication,
 )
 from pycraftcore.application_configuration.enum.run_type_environment import (
     RunTypeEnvironment,
 )
-from pycraftcore.application_configuration.model.connector import ConnectorTyping
-from pycraftcore.application_configuration.model.operation import OperationTyping
+from pycraftcore.application_configuration.model.connector import ConnectorRegistry
+from pycraftcore.application_configuration.model.operation import OperationRegistry
 
 
 @dataclass(frozen=True, slots=True)
 class ApplicationConfiguration:
     env: RunTypeEnvironment
     run: RunTypeApplication
-    connector: dict[ConnectorType, dict[str, ConnectorTyping]]
-    operation: dict[str, OperationTyping]
+    connector: ConnectorRegistry
+    operation: OperationRegistry

pycraftcore-0.2.2/src/pycraftcore/application_configuration/model/connector.py

@@ -0,0 +1,104 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Literal, overload
+
+from pycraftcore.application_configuration.enum.connector_type import ConnectorType
+from pycraftcore.authentication import AuthTyping
+
+
+@dataclass(slots=True)
+class BaseConnector:
+    name: str
+    type: ConnectorType
+    auth: AuthTyping
+
+
+@dataclass(slots=True)
+class ApiConnector(BaseConnector):
+    base_url: str
+    timeout: int
+    retry: int
+    certificate: str | None = field(default=None)
+
+
+@dataclass(slots=True)
+class DatabaseConnector(BaseConnector):
+    engine: str
+    host: str
+    port: int
+    default_name: str
+    pool: dict[str, int]
+
+
+@dataclass(slots=True)
+class FileConnector(BaseConnector):
+    base_path: str
+
+
+@dataclass(slots=True)
+class TelemetryConnector(BaseConnector):
+    host: str
+    port: int
+
+
+ConnectorTyping = ApiConnector | FileConnector | DatabaseConnector | TelemetryConnector
+
+_CONNECTOR_CLASS_BY_TYPE: dict[ConnectorType, type[ConnectorTyping]] = {
+    ConnectorType.api: ApiConnector,
+    ConnectorType.database: DatabaseConnector,
+    ConnectorType.file: FileConnector,
+    ConnectorType.telemetry: TelemetryConnector,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectorRegistry:
+    by_type: dict[ConnectorType, dict[str, ConnectorTyping]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for kind, bucket in self.by_type.items():
+            expected = _CONNECTOR_CLASS_BY_TYPE.get(kind)
+            if expected is None:
+                continue
+            for name, connector in bucket.items():
+                if not isinstance(connector, expected):
+                    raise TypeError(
+                        f"connector {name!r} declared under {kind.value!r} must be a "
+                        f"{expected.__name__}, got {type(connector).__name__}"
+                    )
+
+    @overload
+    def __getitem__(self, kind: Literal[ConnectorType.api]) -> Mapping[str, ApiConnector]: ...
+    @overload
+    def __getitem__(
+        self, kind: Literal[ConnectorType.database]
+    ) -> Mapping[str, DatabaseConnector]: ...
+    @overload
+    def __getitem__(self, kind: Literal[ConnectorType.file]) -> Mapping[str, FileConnector]: ...
+    @overload
+    def __getitem__(
+        self, kind: Literal[ConnectorType.telemetry]
+    ) -> Mapping[str, TelemetryConnector]: ...
+
+    def __getitem__(self, kind: ConnectorType) -> Mapping[str, ConnectorTyping]:
+        return self.by_type.get(kind, {})
+
+    def api(self, name: str) -> ApiConnector:
+        return self._get(ConnectorType.api, name, ApiConnector)
+
+    def database(self, name: str) -> DatabaseConnector:
+        return self._get(ConnectorType.database, name, DatabaseConnector)
+
+    def file(self, name: str) -> FileConnector:
+        return self._get(ConnectorType.file, name, FileConnector)
+
+    def telemetry(self, name: str) -> TelemetryConnector:
+        return self._get(ConnectorType.telemetry, name, TelemetryConnector)
+
+    def _get[T: ConnectorTyping](self, kind: ConnectorType, name: str, expected: type[T]) -> T:
+        try:
+            connector = self.by_type[kind][name]
+        except KeyError:
+            raise KeyError(f"no {kind.value} connector named {name!r}") from None
+        assert isinstance(connector, expected)
+        return connector

pycraftcore-0.2.2/src/pycraftcore/application_configuration/model/operation.py

@@ -0,0 +1,81 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from pycraftcore.application_configuration.enum.file_operation_action import (
+    FileOperationAction,
+)
+from pycraftcore.application_configuration.enum.operation_type import OperationType
+from pycraftcore.application_configuration.model.connector import (
+    ApiConnector,
+    FileConnector,
+)
+from pycraftcore.http.enum.http_method import HttpMethod
+
+
+@dataclass(slots=True)
+class BaseOperation:
+    name: str
+    type: OperationType
+
+
+@dataclass(slots=True)
+class ApiOperation(BaseOperation):
+    connector: ApiConnector
+    endpoint: str
+    method: HttpMethod
+    parameters: dict[str, Any]
+
+
+@dataclass(slots=True)
+class FileOperation(BaseOperation):
+    connector: FileConnector
+    action: FileOperationAction
+    parameters: dict[str, Any]
+
+
+OperationTyping = FileOperation | ApiOperation
+
+_OPERATION_CLASS_BY_TYPE: dict[OperationType, type[OperationTyping]] = {
+    OperationType.api: ApiOperation,
+    OperationType.file: FileOperation,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class OperationRegistry:
+    """Operations keyed by name, with per-kind typed lookups.
+
+    Mirrors `ConnectorRegistry`: each operation declares its own `OperationType`, and a
+    mismatch between that declared type and its concrete dataclass is rejected eagerly here
+    instead of surfacing later as a wrong-typed lookup.
+    """
+
+    by_name: dict[str, OperationTyping] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for name, operation in self.by_name.items():
+            expected = _OPERATION_CLASS_BY_TYPE.get(operation.type)
+            if expected is None:
+                continue
+            if not isinstance(operation, expected):
+                raise TypeError(
+                    f"operation {name!r} declared type {operation.type.value!r} but is a "
+                    f"{type(operation).__name__}, expected {expected.__name__}"
+                )
+
+    def api(self, name: str) -> ApiOperation:
+        return self._get(name, ApiOperation)
+
+    def file(self, name: str) -> FileOperation:
+        return self._get(name, FileOperation)
+
+    def _get[T: OperationTyping](self, name: str, expected: type[T]) -> T:
+        try:
+            operation = self.by_name[name]
+        except KeyError:
+            raise KeyError(f"no operation named {name!r}") from None
+        if not isinstance(operation, expected):
+            raise TypeError(
+                f"operation {name!r} is a {type(operation).__name__}, not {expected.__name__}"
+            )
+        return operation