stapel-recordings 0.1.0__tar.gz

stapel_recordings-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_recordings-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: stapel-recordings
+Version: 0.1.0
+Summary: Recording lifecycle and transcription for the Stapel framework
+License: MIT
+Keywords: django,stapel,recordings
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == "s3"
+Provides-Extra: all
+Requires-Dist: stapel-recordings[s3]; extra == "all"
+Dynamic: license-file
+
+# stapel-recordings
+
+Recording lifecycle and transcription for the [Stapel framework](https://github.com/usestapel) —
+composable Django apps that deploy as a monolith or as microservices
+without changing module code.
+
+Owns the lifecycle **capture/upload → storage → transcribe → summarize**:
+`Recording` + `Speaker` + `Segment` (the unified transcript), presigned /
+multipart upload sessions, and a data-driven, outbox-backed processing
+pipeline with retry, DLQ and reconcile.
+
+Speech-to-text and summarization are **delegated to
+[stapel-agent](https://github.com/usestapel/stapel-agent)** via the
+`llm.transcribe` / `llm.summarize` comm Functions — this module does not
+implement STT or LLM calls. Object storage goes through a swappable seam.
+
+## Install
+
+```bash
+pip install stapel-recordings          # default: Django-storage backend
+pip install "stapel-recordings[s3]"    # + boto3 S3/MinIO backend
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_core.django.outbox",   # transactional outbox (pipeline reliability)
+    "stapel_recordings",
+]
+
+# urls.py
+path("recordings/", include("stapel_recordings.urls"))
+```
+
+The `transcribe` / `merge` stages call stapel-agent by comm name — install
+and configure stapel-agent (or provide `llm.transcribe` / `llm.summarize`
+providers) for the pipeline to complete. The default `convert` stage needs
+`ffmpeg`/`ffprobe` on PATH (or set `NORMALIZER` to `passthrough_normalize`).
+
+## The pipeline is data you can edit
+
+```python
+STAPEL_RECORDINGS = {
+    # Reorder / subset / insert stages — no fork:
+    "PIPELINE": ["convert", "transcribe", "redact_pii", "merge"],
+    # Replace or add stage handlers (merge-over-builtins; None removes):
+    "STAGES": {"diarize": "myproject.stages.PyannoteDiarizer"},
+    # Or source the list at runtime (DB / per-workspace / per-recording):
+    "PIPELINE_RESOLVER": "myproject.pipelines.resolve",
+    # Swap the object store:
+    "STORAGE": "stapel_recordings.storage.S3Backend",
+}
+```
+
+A generic driver runs the resolved stage list, advancing the status machine
+and emitting the next stage through the outbox. See **[MODULE.md](MODULE.md)**
+for the stage contract and worked examples.
+
+## Settings
+
+All configuration lives in the `STAPEL_RECORDINGS` namespace (dict setting,
+flat setting, or env var — resolved lazily). See the full table in
+[MODULE.md](MODULE.md). Highlights: `PIPELINE`, `STAGES`,
+`PIPELINE_RESOLVER`, `STORAGE`, `NORMALIZER`, `SUMMARIZE_ENABLED`,
+`MAX_STAGE_RETRIES`.
+
+## comm surface
+
+| Kind | Name | Contract |
+|---|---|---|
+| Action (emit) | `recording.uploaded`, `recording.stage_completed`, `recording.completed`, `recording.failed` | pipeline lifecycle (public) |
+| Action (consume) | `recording.uploaded`, `recording.stage`, `user.deleted` | driver + GDPR erase |
+| Function (call) | `llm.transcribe`, `llm.summarize` | provided by stapel-agent |
+
+## Operations
+
+```bash
+python manage.py recordings_reconcile --once   # re-drive stuck recordings
+```
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff jsonschema djangorestframework
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT

stapel_recordings-0.1.0/README.md

@@ -0,0 +1,91 @@
+# stapel-recordings
+
+Recording lifecycle and transcription for the [Stapel framework](https://github.com/usestapel) —
+composable Django apps that deploy as a monolith or as microservices
+without changing module code.
+
+Owns the lifecycle **capture/upload → storage → transcribe → summarize**:
+`Recording` + `Speaker` + `Segment` (the unified transcript), presigned /
+multipart upload sessions, and a data-driven, outbox-backed processing
+pipeline with retry, DLQ and reconcile.
+
+Speech-to-text and summarization are **delegated to
+[stapel-agent](https://github.com/usestapel/stapel-agent)** via the
+`llm.transcribe` / `llm.summarize` comm Functions — this module does not
+implement STT or LLM calls. Object storage goes through a swappable seam.
+
+## Install
+
+```bash
+pip install stapel-recordings          # default: Django-storage backend
+pip install "stapel-recordings[s3]"    # + boto3 S3/MinIO backend
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_core.django.outbox",   # transactional outbox (pipeline reliability)
+    "stapel_recordings",
+]
+
+# urls.py
+path("recordings/", include("stapel_recordings.urls"))
+```
+
+The `transcribe` / `merge` stages call stapel-agent by comm name — install
+and configure stapel-agent (or provide `llm.transcribe` / `llm.summarize`
+providers) for the pipeline to complete. The default `convert` stage needs
+`ffmpeg`/`ffprobe` on PATH (or set `NORMALIZER` to `passthrough_normalize`).
+
+## The pipeline is data you can edit
+
+```python
+STAPEL_RECORDINGS = {
+    # Reorder / subset / insert stages — no fork:
+    "PIPELINE": ["convert", "transcribe", "redact_pii", "merge"],
+    # Replace or add stage handlers (merge-over-builtins; None removes):
+    "STAGES": {"diarize": "myproject.stages.PyannoteDiarizer"},
+    # Or source the list at runtime (DB / per-workspace / per-recording):
+    "PIPELINE_RESOLVER": "myproject.pipelines.resolve",
+    # Swap the object store:
+    "STORAGE": "stapel_recordings.storage.S3Backend",
+}
+```
+
+A generic driver runs the resolved stage list, advancing the status machine
+and emitting the next stage through the outbox. See **[MODULE.md](MODULE.md)**
+for the stage contract and worked examples.
+
+## Settings
+
+All configuration lives in the `STAPEL_RECORDINGS` namespace (dict setting,
+flat setting, or env var — resolved lazily). See the full table in
+[MODULE.md](MODULE.md). Highlights: `PIPELINE`, `STAGES`,
+`PIPELINE_RESOLVER`, `STORAGE`, `NORMALIZER`, `SUMMARIZE_ENABLED`,
+`MAX_STAGE_RETRIES`.
+
+## comm surface
+
+| Kind | Name | Contract |
+|---|---|---|
+| Action (emit) | `recording.uploaded`, `recording.stage_completed`, `recording.completed`, `recording.failed` | pipeline lifecycle (public) |
+| Action (consume) | `recording.uploaded`, `recording.stage`, `user.deleted` | driver + GDPR erase |
+| Function (call) | `llm.transcribe`, `llm.summarize` | provided by stapel-agent |
+
+## Operations
+
+```bash
+python manage.py recordings_reconcile --once   # re-drive stuck recordings
+```
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff jsonschema djangorestframework
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT

stapel_recordings-0.1.0/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-recordings — Recording lifecycle and transcription for the Stapel framework.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``recordings_settings`` — resolved app settings (``stapel_recordings.conf``).
+"""
+
+__all__ = [
+    "recordings_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_recordings` stays Django-free.
+_LAZY_EXPORTS = {
+    "recordings_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_recordings-0.1.0/actions.py

@@ -0,0 +1,51 @@
+"""Action subscriptions of stapel-recordings.
+
+Handlers are idempotent (delivery is at-least-once — outbox retries, broker
+redelivery). Transport is chosen by ``STAPEL_COMM`` (in-process in a
+monolith, bus consumer in microservices); the handler code is identical.
+"""
+import logging
+
+from stapel_core.comm import on_action
+
+from . import events
+
+logger = logging.getLogger(__name__)
+
+
+@on_action(events.ACTION_UPLOADED)
+def handle_uploaded(event):
+    """A file landed — start the pipeline driver."""
+    from .pipeline import start_pipeline
+
+    recording_id = event.payload.get("recording_id")
+    if not recording_id:
+        logger.error("recording.uploaded without recording_id: %s", event.event_id)
+        return
+    start_pipeline(recording_id)
+
+
+@on_action(events.ACTION_STAGE)
+def handle_stage(event):
+    """Run one stage of the resolved pipeline (the generic driver step)."""
+    from .pipeline import run_stage
+
+    recording_id = event.payload.get("recording_id")
+    stage_index = event.payload.get("stage_index")
+    if recording_id is None or stage_index is None:
+        logger.error("recording.stage missing fields: %s", event.event_id)
+        return
+    run_stage(recording_id, int(stage_index))
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase a user's recordings + their storage objects (GDPR Art. 17)."""
+    from .gdpr import RecordingsGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    RecordingsGDPRProvider().delete(user_id)
+    logger.info("recordings erased for deleted user %s", user_id)

stapel_recordings-0.1.0/admin.py

@@ -0,0 +1,43 @@
+"""Read-only admin for the recordings journal models."""
+from django.contrib import admin
+
+from .models import Job, Recording, Segment, Speaker, UploadSession
+
+
+class _ReadOnlyAdmin(admin.ModelAdmin):
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(Recording)
+class RecordingAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "title", "status", "workspace_id", "provider_used", "created_at")
+    list_filter = ("status", "source_type")
+    search_fields = ("id", "title", "workspace_id")
+
+
+@admin.register(Speaker)
+class SpeakerAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "recording", "label", "display_name")
+
+
+@admin.register(Segment)
+class SegmentAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "recording", "sequence_num", "start_time", "end_time")
+
+
+@admin.register(UploadSession)
+class UploadSessionAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "recording", "is_multipart", "finalized_at", "expires_at")
+
+
+@admin.register(Job)
+class JobAdmin(_ReadOnlyAdmin):
+    list_display = ("id", "recording", "type", "status", "progress_percent")
+    list_filter = ("type", "status")

stapel_recordings-0.1.0/apps.py

@@ -0,0 +1,27 @@
+from django.apps import AppConfig
+
+
+class RecordingsConfig(AppConfig):
+    name = "stapel_recordings"
+    label = "recordings"
+    verbose_name = "Recording lifecycle and transcription"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Import-time side effects: system checks, error-key registration,
+        # action subscriptions (pipeline driver + GDPR consumer). Keep each
+        # in its own module.
+        from . import checks  # noqa: F401
+        from . import errors  # noqa: F401
+
+        # Action subscriptions (in-process in a monolith, bus consumer in
+        # microservices — same code, transport chosen by STAPEL_COMM).
+        from . import actions  # noqa: F401
+
+        # GDPR provider registration (monolith mode).
+        from stapel_core.gdpr import gdpr_registry
+
+        from .gdpr import RecordingsGDPRProvider
+
+        if RecordingsGDPRProvider().section not in gdpr_registry.sections:
+            gdpr_registry.register(RecordingsGDPRProvider())

stapel_recordings-0.1.0/checks.py

@@ -0,0 +1,66 @@
+"""Django system checks for stapel-recordings configuration.
+
+Policy (docs/library-standard.md §3.7): E-level for configuration the
+service cannot run with; W-level for entries that degrade lazily (a broken
+*unused* dotted path must not block deploys).
+"""
+from django.core import checks
+
+
+@checks.register(checks.Tags.compatibility)
+def check_storage_backend(app_configs, **kwargs):
+    """E: the STORAGE seam must resolve to a RecordingStorage subclass."""
+    from .conf import recordings_settings
+    from .storage import RecordingStorage
+
+    try:
+        cls = recordings_settings.STORAGE
+    except Exception as exc:
+        return [checks.Error(
+            f"STAPEL_RECORDINGS['STORAGE'] could not be imported: {exc}",
+            id="stapel_recordings.E001",
+        )]
+    if not (isinstance(cls, type) and issubclass(cls, RecordingStorage)):
+        return [checks.Error(
+            "STAPEL_RECORDINGS['STORAGE'] must be a RecordingStorage subclass.",
+            id="stapel_recordings.E002",
+        )]
+    return []
+
+
+@checks.register(checks.Tags.compatibility)
+def check_pipeline_stages(app_configs, **kwargs):
+    """W: every stage named in PIPELINE should resolve in the registry; the
+    NORMALIZER / PIPELINE_RESOLVER seams should be importable and callable."""
+    from .conf import recordings_settings
+    from .stages import resolve_stages
+
+    warnings = []
+    try:
+        known = set(resolve_stages().keys())
+    except Exception as exc:
+        return [checks.Warning(
+            f"STAPEL_RECORDINGS['STAGES'] overlay could not be resolved: {exc}",
+            id="stapel_recordings.W001",
+        )]
+    for name in recordings_settings.PIPELINE:
+        if name not in known:
+            warnings.append(checks.Warning(
+                f"PIPELINE references stage {name!r} that is not registered "
+                "(register it via register_stage or add it to STAGES).",
+                id="stapel_recordings.W002",
+            ))
+    for key in ("NORMALIZER", "PIPELINE_RESOLVER"):
+        try:
+            value = getattr(recordings_settings, key)
+            if not callable(value):
+                warnings.append(checks.Warning(
+                    f"STAPEL_RECORDINGS['{key}'] is not callable.",
+                    id="stapel_recordings.W003",
+                ))
+        except Exception as exc:
+            warnings.append(checks.Warning(
+                f"STAPEL_RECORDINGS['{key}'] could not be imported: {exc}",
+                id="stapel_recordings.W004",
+            ))
+    return warnings

stapel_recordings-0.1.0/conf.py

@@ -0,0 +1,72 @@
+"""Settings namespace for stapel-recordings.
+
+All configuration is read through ``recordings_settings`` (lazily, at call
+time) — never via module-level ``os.getenv`` (values would freeze at import).
+Resolution order per key: ``settings.STAPEL_RECORDINGS`` dict -> flat Django
+setting of the same name -> environment variable -> default below.
+
+Dotted-path keys listed in ``import_strings`` are resolved with
+``import_string`` — the fork-free escape hatch for swappable behavior
+(the STORAGE / NORMALIZER strategies and the PIPELINE_RESOLVER seam).
+
+The flagship extension point is the **pipeline**: an ordered list of stage
+names (``PIPELINE``) run by a generic driver over an open stage registry
+(``STAGES`` overlay + ``register_stage`` runtime API). Reorder, subset,
+insert or replace stages without forking. See MODULE.md.
+"""
+from stapel_core.conf import AppSettings
+
+#: Default pipeline: the four built-in stages in canonical order. Hosts
+#: override with STAPEL_RECORDINGS["PIPELINE"] (reorder / subset / extend)
+#: or a PIPELINE_RESOLVER for runtime/per-recording definitions.
+DEFAULT_PIPELINE = ("convert", "transcribe", "diarize", "merge")
+
+recordings_settings = AppSettings(
+    "STAPEL_RECORDINGS",
+    defaults={
+        # ── Pipeline (flagship extension point) ──────────────────────
+        # Ordered stage-name list run by the generic driver. A host can
+        # reorder, drop (e.g. skip "diarize") or insert stages (e.g. a
+        # "redact_pii" before "merge") purely by changing this list.
+        "PIPELINE": list(DEFAULT_PIPELINE),
+        # Overlay of custom/replacement stage handlers: {name: dotted-path}.
+        # Merge-over-builtins semantics; a value of None removes a built-in.
+        "STAGES": {},
+        # Resolver seam: dotted path to ``(recording) -> list[str]``. The
+        # default returns the PIPELINE setting; point it at a DB / per-
+        # workspace source to let operators edit pipelines at runtime.
+        "PIPELINE_RESOLVER": "stapel_recordings.pipeline.default_pipeline_resolver",
+
+        # ── Storage seam (single strategy, replace) ──────────────────
+        # Dotted path to a RecordingStorage implementation. Default is a
+        # Django-storage backend (works with any DEFAULT_FILE_STORAGE);
+        # swap for the bundled S3/MinIO backend or your own.
+        "STORAGE": "stapel_recordings.storage.DjangoStorageBackend",
+        "STORAGE_PREFIX": "recordings",
+
+        # ── Audio normalization seam (single strategy, replace) ──────
+        # Dotted path to ``(src_path, dst_path) -> float|None`` returning
+        # duration seconds. Default shells out to ffmpeg; a passthrough is
+        # provided for environments without ffmpeg / for tests.
+        "NORMALIZER": "stapel_recordings.normalize.ffmpeg_normalize",
+
+        # ── Upload sessions ──────────────────────────────────────────
+        "UPLOAD_SESSION_TTL_SECONDS": 15 * 60,
+        "MULTIPART_SESSION_TTL_SECONDS": 24 * 60 * 60,
+        "MULTIPART_PART_SIZE": 10 * 1024 * 1024,
+        "MAX_UPLOAD_BYTES": 2 * 1024 * 1024 * 1024,
+
+        # ── Transcription / summarization (delegated to stapel-agent) ─
+        "TRANSCRIBE_TIMEOUT_SECONDS": 1800,
+        "MAX_STAGE_RETRIES": 3,
+        "SUMMARIZE_ENABLED": True,
+        "SUMMARIZE_MODEL": "medium",
+
+        # ── Reconcile watchdog ───────────────────────────────────────
+        "STUCK_THRESHOLD_SECONDS": 10 * 60,
+        "ABANDONED_UPLOAD_THRESHOLD_SECONDS": 60 * 60,
+    },
+    import_strings=("STORAGE", "NORMALIZER", "PIPELINE_RESOLVER"),
+)
+
+__all__ = ["recordings_settings", "DEFAULT_PIPELINE"]

stapel_recordings-0.1.0/conftest.py

@@ -0,0 +1,78 @@
+def pytest_configure(config):
+    from django.conf import settings
+    if not settings.configured:
+        settings.configure(
+            SECRET_KEY="test-secret-key-not-for-production",
+            INSTALLED_APPS=[
+                "django.contrib.contenttypes",
+                "django.contrib.auth",
+                "django.contrib.sessions",
+                "django.contrib.admin",
+                "django.contrib.messages",
+                "stapel_core.django.users",
+                "stapel_core.django.outbox",
+                "rest_framework",
+                "stapel_recordings",
+            ],
+            AUTH_USER_MODEL="users.User",
+            DATABASES={
+                "default": {
+                    "ENGINE": "django.db.backends.sqlite3",
+                    "NAME": ":memory:",
+                }
+            },
+            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+            USE_TZ=True,
+            ROOT_URLCONF="stapel_recordings.tests.urls",
+            MEDIA_ROOT="/tmp/stapel-recordings-test-media",
+            CACHES={
+                "default": {
+                    "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+                }
+            },
+            # Realistic comm: Actions leave through the transactional outbox
+            # (so producer/consumer can be tested as split synchronous halves,
+            # §7.21) and schema validation is ON — the committed contracts in
+            # schemas/ are enforced by the tests.
+            STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+            STAPEL_COMM={
+                "OUTBOX_ENABLED": True,
+                "ACTION_TRANSPORT": "inprocess",
+                "FUNCTION_TRANSPORT": "inprocess",
+                "VALIDATE_SCHEMAS": True,
+            },
+            MIGRATION_MODULES={
+                "users": None,
+                "recordings": None,
+            },
+        )
+        import django
+        django.setup()
+
+        from stapel_core.comm.schemas import autoload_schemas
+        autoload_schemas()
+
+
+import pytest  # noqa: E402
+
+
+@pytest.fixture
+def api_client():
+    from rest_framework.test import APIClient
+    return APIClient()
+
+
+@pytest.fixture(autouse=True)
+def _reset_recordings_state():
+    """Isolate runtime stage registrations, the storage-backend cache, and
+    any stub comm Functions between tests."""
+    from stapel_core.comm.registry import function_registry
+
+    from stapel_recordings import stages, storage
+
+    yield
+    stages.reset_runtime_stages()
+    storage.reset_storage_cache()
+    for name in ("llm.transcribe", "llm.summarize"):
+        function_registry._providers.pop(name, None)
+        function_registry._schemas.pop(name, None)

stapel_recordings-0.1.0/dto.py

@@ -0,0 +1,71 @@
+"""Dataclass DTOs — the API models of stapel-recordings (never ORM instances)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class RecordingDTO:
+    """A recording as seen by the API."""
+
+    id: str
+    workspace_id: str
+    title: str
+    status: str
+    source_type: str
+    language: Optional[str]
+    duration_seconds: Optional[float]
+    segments_count: int
+    speakers_count: int
+    word_count: int
+    provider_used: Optional[str]
+    transcript_storage_key: Optional[str]
+    summary: Optional[str]
+    created_at: str
+
+
+@dataclass
+class UploadSessionDTO:
+    """A single-PUT upload session."""
+
+    id: str
+    presigned_url: str
+    storage_key: str
+    max_size_bytes: int
+    expires_at: str
+
+
+@dataclass
+class CreateRecordingResponse:
+    recording: RecordingDTO
+    upload: UploadSessionDTO
+
+
+def recording_to_dto(recording) -> RecordingDTO:
+    return RecordingDTO(
+        id=str(recording.id),
+        workspace_id=str(recording.workspace_id),
+        title=recording.title,
+        status=recording.status,
+        source_type=recording.source_type,
+        language=recording.language,
+        duration_seconds=recording.duration_seconds,
+        segments_count=recording.segments_count,
+        speakers_count=recording.speakers_count,
+        word_count=recording.word_count,
+        provider_used=recording.provider_used,
+        transcript_storage_key=recording.transcript_storage_key,
+        summary=recording.summary,
+        created_at=recording.created_at.isoformat(),
+    )
+
+
+def upload_session_to_dto(session) -> UploadSessionDTO:
+    return UploadSessionDTO(
+        id=str(session.id),
+        presigned_url=session.presigned_url,
+        storage_key=session.storage_key,
+        max_size_bytes=session.max_size_bytes,
+        expires_at=session.expires_at.isoformat(),
+    )