Merge remote-tracking branch 'origin/main' into feat/inworld-tts

# Conflicts:
#	api/services/configuration/registry.py

api/alembic/versions/2159d4ac431a_added_quota_tables.py

@@ -18,6 +18,9 @@ branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 
 
+DEPRECATED_QUOTA_COMMENT = "Deprecated. MPS owns quota and credit ledger state."
+
+
 def upgrade() -> None:
     # ### commands auto generated by Alembic - please adjust! ###
     # 1) Create the `quota_type` enum *before* we add the column that references it.
@@ -34,7 +37,12 @@ def upgrade() -> None:
         sa.Column("organization_id", sa.Integer(), nullable=False),
         sa.Column("period_start", sa.DateTime(), nullable=False),
         sa.Column("period_end", sa.DateTime(), nullable=False),
-        sa.Column("quota_dograh_tokens", sa.Integer(), nullable=False),
+        sa.Column(
+            "quota_dograh_tokens",
+            sa.Integer(),
+            nullable=False,
+            comment=DEPRECATED_QUOTA_COMMENT,
+        ),
         sa.Column("used_dograh_tokens", sa.Integer(), nullable=False),
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=True),
         sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
@@ -63,7 +71,11 @@ def upgrade() -> None:
     op.add_column(
         "organizations",
         sa.Column(
-            "quota_type", quota_type_enum, nullable=False, server_default="monthly"
+            "quota_type",
+            quota_type_enum,
+            nullable=False,
+            server_default="monthly",
+            comment=DEPRECATED_QUOTA_COMMENT,
         ),
     )
     op.add_column(
@@ -73,6 +85,7 @@ def upgrade() -> None:
             sa.Integer(),
             nullable=False,
             server_default=sa.text("0"),
+            comment=DEPRECATED_QUOTA_COMMENT,
         ),
     )
     op.add_column(
@@ -82,10 +95,17 @@ def upgrade() -> None:
             sa.Integer(),
             nullable=False,
             server_default=sa.text("LEAST(EXTRACT(DAY FROM CURRENT_DATE)::int, 28)"),
+            comment=DEPRECATED_QUOTA_COMMENT,
         ),
     )
     op.add_column(
-        "organizations", sa.Column("quota_start_date", sa.DateTime(), nullable=True)
+        "organizations",
+        sa.Column(
+            "quota_start_date",
+            sa.DateTime(),
+            nullable=True,
+            comment=DEPRECATED_QUOTA_COMMENT,
+        ),
     )
     op.add_column(
         "organizations",
@@ -94,6 +114,7 @@ def upgrade() -> None:
             sa.Boolean(),
             nullable=False,
             server_default=sa.text("false"),
+            comment=DEPRECATED_QUOTA_COMMENT,
         ),
     )
     # ### end Alembic commands ###

api/alembic/versions/91cc6ba3e1c7_add_key_to_user_configurations.py

@@ -0,0 +1,52 @@
+"""add key to user_configurations
+
+Turns user_configurations into a per-user keyed JSON store mirroring
+organization_configurations. Existing rows (the legacy v1 AI model
+configuration blob) are backfilled with key MODEL_CONFIGURATION.
+
+Revision ID: 91cc6ba3e1c7
+Revises: efe356f488f9
+Create Date: 2026-06-12 21:04:25.561529
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "91cc6ba3e1c7"
+down_revision: Union[str, None] = "efe356f488f9"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Backfill existing rows (all legacy model-config blobs) via the server
+    # default, then drop the default — application code always supplies key.
+    op.add_column(
+        "user_configurations",
+        sa.Column(
+            "key",
+            sa.String(),
+            nullable=False,
+            server_default="MODEL_CONFIGURATION",
+        ),
+    )
+
+    op.create_unique_constraint(
+        "_user_configuration_key_uc", "user_configurations", ["user_id", "key"]
+    )
+    op.alter_column("user_configurations", "key", server_default=None)
+
+
+def downgrade() -> None:
+    op.drop_constraint(
+        "_user_configuration_key_uc", "user_configurations", type_="unique"
+    )
+    # Non-model-config rows (e.g. ONBOARDING) have no meaning in the old
+    # single-blob schema; the old code would read them as the user's model
+    # config, so they must not survive the downgrade.
+    op.execute("DELETE FROM user_configurations WHERE key != 'MODEL_CONFIGURATION'")
+    op.drop_column("user_configurations", "key")

api/alembic/versions/c425d3445750_add_columns_in_usage_table.py

@@ -18,6 +18,9 @@ branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 
 
+DEPRECATED_QUOTA_COMMENT = "Deprecated. MPS owns quota and credit ledger state."
+
+
 def upgrade() -> None:
     # ### commands auto generated by Alembic - please adjust! ###
     op.add_column(
@@ -26,7 +29,12 @@ def upgrade() -> None:
     )
     op.add_column(
         "organization_usage_cycles",
-        sa.Column("quota_amount_usd", sa.Float(), nullable=True),
+        sa.Column(
+            "quota_amount_usd",
+            sa.Float(),
+            nullable=True,
+            comment=DEPRECATED_QUOTA_COMMENT,
+        ),
     )
     # ### end Alembic commands ###
 

api/alembic/versions/efe356f488f9_add_extra_column_in_workflow_runs.py

@@ -0,0 +1,34 @@
+"""add extra column in workflow runs
+
+Revision ID: efe356f488f9
+Revises: 384be6596b36
+Create Date: 2026-06-16 12:24:30.081058
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "efe356f488f9"
+down_revision: Union[str, None] = "384be6596b36"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "workflow_runs",
+        sa.Column(
+            "extra",
+            sa.JSON(),
+            server_default=sa.text("'{}'::json"),
+            nullable=False,
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("workflow_runs", "extra")

api/constants.py

@@ -30,6 +30,12 @@ CORS_ALLOWED_ORIGINS = [
     o.strip() for o in os.getenv("CORS_ALLOWED_ORIGINS", "").split(",") if o.strip()
 ]
 AUTH_PROVIDER = os.getenv("AUTH_PROVIDER", "local")
+# Stack Auth public client config. These are safe to expose to the browser (the
+# publishable client key is public by design, and the project id is non-sensitive),
+# and are served to the UI at runtime via /api/v1/health so the frontend no longer
+# needs them baked into the bundle at build time.
+STACK_AUTH_PROJECT_ID = os.getenv("STACK_AUTH_PROJECT_ID")
+STACK_PUBLISHABLE_CLIENT_KEY = os.getenv("STACK_PUBLISHABLE_CLIENT_KEY")
 DOGRAH_MPS_SECRET_KEY = os.getenv("DOGRAH_MPS_SECRET_KEY", None)
 MPS_API_URL = os.getenv("MPS_API_URL", "https://services.dograh.com")
 

api/db/campaign_client.py

@@ -9,6 +9,8 @@ from api.db.base_client import BaseDBClient
 from api.db.filters import apply_workflow_run_filters, get_workflow_run_order_clause
 from api.db.models import CampaignModel, QueuedRunModel, WorkflowRunModel
 from api.schemas.workflow import WorkflowRunResponseSchema
+from api.services.workflow.run_usage_response import format_public_cost_info
+from api.utils.recording_artifacts import get_recording_storage_key
 
 
 class CampaignClient(BaseDBClient):
@@ -44,9 +46,11 @@ class CampaignClient(BaseDBClient):
                 source_id=source_id,
                 created_by=user_id,
                 organization_id=organization_id,
-                retry_config=retry_config
-                if retry_config
-                else CampaignModel.retry_config.default.arg,
+                retry_config=(
+                    retry_config
+                    if retry_config
+                    else CampaignModel.retry_config.default.arg
+                ),
                 orchestrator_metadata=orchestrator_metadata,
                 telephony_configuration_id=telephony_configuration_id,
             )
@@ -215,26 +219,15 @@ class CampaignClient(BaseDBClient):
                         "is_completed": run.is_completed,
                         "recording_url": run.recording_url,
                         "transcript_url": run.transcript_url,
-                        "cost_info": {
-                            "dograh_token_usage": (
-                                run.cost_info.get("dograh_token_usage")
-                                if run.cost_info
-                                and "dograh_token_usage" in run.cost_info
-                                else round(
-                                    float(run.cost_info.get("total_cost_usd", 0)) * 100,
-                                    2,
-                                )
-                                if run.cost_info and "total_cost_usd" in run.cost_info
-                                else 0
-                            ),
-                            "call_duration_seconds": int(
-                                round(run.cost_info.get("call_duration_seconds") or 0)
-                            )
-                            if run.cost_info
-                            else None,
-                        }
-                        if run.cost_info
-                        else None,
+                        "user_recording_url": get_recording_storage_key(
+                            run.extra, "user"
+                        ),
+                        "bot_recording_url": get_recording_storage_key(
+                            run.extra, "bot"
+                        ),
+                        "cost_info": format_public_cost_info(
+                            run.cost_info, run.usage_info
+                        ),
                         "definition_id": run.definition_id,
                         "initial_context": run.initial_context,
                         "gathered_context": run.gathered_context,
@@ -286,9 +279,11 @@ class CampaignClient(BaseDBClient):
                 source_id=parent_campaign.source_id,
                 created_by=parent_campaign.created_by,
                 organization_id=parent_campaign.organization_id,
-                retry_config=retry_config
-                if retry_config
-                else CampaignModel.retry_config.default.arg,
+                retry_config=(
+                    retry_config
+                    if retry_config
+                    else CampaignModel.retry_config.default.arg
+                ),
                 orchestrator_metadata=child_meta,
                 rate_limit_per_second=parent_campaign.rate_limit_per_second,
                 total_rows=len(queued_runs_data),
@@ -354,8 +349,7 @@ class CampaignClient(BaseDBClient):
         # Retries create new queued_runs with suffixed source_uuids linked via
         # parent_queued_run_id, so group by the ROOT queued_run using a
         # recursive walk and pick the latest workflow_run across the tree.
-        sql = text(
-            f"""
+        sql = text(f"""
             WITH RECURSIVE run_tree AS (
                 SELECT id AS root_id, id AS run_id
                 FROM queued_runs
@@ -382,8 +376,7 @@ class CampaignClient(BaseDBClient):
             JOIN latest_run_per_root lr ON lr.root_id = q0.id
             WHERE q0.campaign_id = :cid
               AND ({tag_filter})
-            """
-        )
+            """)
 
         async with self.async_session() as session:
             result = await session.execute(sql, {"cid": campaign_id})
@@ -662,7 +655,7 @@ class CampaignClient(BaseDBClient):
         async with self.async_session() as session:
             conditions = [
                 WorkflowRunModel.is_completed.is_(True),
-                WorkflowRunModel.cost_info["call_duration_seconds"]
+                WorkflowRunModel.usage_info["call_duration_seconds"]
                 .as_string()
                 .isnot(None),
             ]
@@ -685,6 +678,7 @@ class CampaignClient(BaseDBClient):
                     WorkflowRunModel.initial_context,
                     WorkflowRunModel.gathered_context,
                     WorkflowRunModel.cost_info,
+                    WorkflowRunModel.usage_info,
                     WorkflowRunModel.public_access_token,
                 )
                 .where(*conditions)

api/db/db_client.py

@@ -53,7 +53,7 @@ class DBClient(
     - UserClient: handles user and user configuration operations
     - OrganizationClient: handles organization operations
     - OrganizationConfigurationClient: handles organization configuration operations
-    - OrganizationUsageClient: handles organization usage and quota operations
+    - OrganizationUsageClient: handles organization usage reporting aggregates
     - IntegrationClient: handles integration operations
     - WorkflowTemplateClient: handles workflow template operations
     - CampaignClient: handles campaign operations

api/db/filters.py

@@ -25,7 +25,7 @@ def get_workflow_run_order_clause(
     """
     # Determine sort column
     if sort_by == "duration":
-        sort_column = WorkflowRunModel.cost_info.op("->>")(
+        sort_column = WorkflowRunModel.usage_info.op("->>")(
             "call_duration_seconds"
         ).cast(Float)
     else:
@@ -43,7 +43,7 @@ def get_workflow_run_order_clause(
 ATTRIBUTE_FIELD_MAPPING = {
     "dateRange": "created_at",
     "dispositionCode": "gathered_context.mapped_call_disposition",
-    "duration": "cost_info.call_duration_seconds",
+    "duration": "usage_info.call_duration_seconds",
     "status": "is_completed",
     "tokenUsage": "cost_info.total_cost_usd",
     "runId": "id",
@@ -208,7 +208,7 @@ def apply_workflow_run_filters(
                 min_val = value.get("min")
                 max_val = value.get("max")
 
-                if field == "cost_info.call_duration_seconds":
+                if field == "usage_info.call_duration_seconds":
                     # Use ->> operator for compatibility with all PostgreSQL versions
                     # (subscript [] only works in PostgreSQL 14+)
                     duration_text = cast(WorkflowRunModel.usage_info, JSONB).op("->>")(

api/db/models.py

@@ -82,12 +82,24 @@ class UserModel(Base):
 
 
 class UserConfigurationModel(Base):
+    """Per-user keyed JSON store, mirroring organization_configurations.
+
+    Keys are defined in UserConfigurationKey. The legacy v1 AI model
+    configuration lives under MODEL_CONFIGURATION; last_validated_at is only
+    meaningful for that key.
+    """
+
     __tablename__ = "user_configurations"
     id = Column(Integer, primary_key=True, index=True)
     user_id = Column(Integer, ForeignKey("users.id"), nullable=True)
+    key = Column(String, nullable=False)
     configuration = Column(JSON, nullable=False, default=dict)
     last_validated_at = Column(DateTime(timezone=True), nullable=True)
 
+    __table_args__ = (
+        UniqueConstraint("user_id", "key", name="_user_configuration_key_uc"),
+    )
+
 
 # New Organization model
 class OrganizationModel(Base):
@@ -97,22 +109,44 @@ class OrganizationModel(Base):
     provider_id = Column(String, unique=True, index=True, nullable=False)
     created_at = Column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
 
-    # Quota fields
+    # Deprecated: MPS owns quota and credit ledger state.
     quota_type = Column(
         Enum("monthly", "annual", name="quota_type"),
         nullable=False,
         default="monthly",
         server_default=text("'monthly'::quota_type"),
+        comment="Deprecated. MPS owns quota and credit ledger state.",
+        info={"deprecated": True},
     )
     quota_dograh_tokens = Column(
-        Integer, nullable=False, default=0, server_default=text("0")
+        Integer,
+        nullable=False,
+        default=0,
+        server_default=text("0"),
+        comment="Deprecated. MPS owns quota and credit ledger state.",
+        info={"deprecated": True},
     )
     quota_reset_day = Column(
-        Integer, nullable=False, default=1, server_default=text("1")
-    )  # 1-28, only for monthly
-    quota_start_date = Column(DateTime(timezone=True), nullable=True)  # Only for annual
+        Integer,
+        nullable=False,
+        default=1,
+        server_default=text("1"),
+        comment="Deprecated. MPS owns quota and credit ledger state.",
+        info={"deprecated": True},
+    )
+    quota_start_date = Column(
+        DateTime(timezone=True),
+        nullable=True,
+        comment="Deprecated. MPS owns quota and credit ledger state.",
+        info={"deprecated": True},
+    )
     quota_enabled = Column(
-        Boolean, nullable=False, default=False, server_default=text("false")
+        Boolean,
+        nullable=False,
+        default=False,
+        server_default=text("false"),
+        comment="Deprecated. MPS owns quota and credit ledger state.",
+        info={"deprecated": True},
     )
 
     price_per_second_usd = Column(Float, nullable=True)
@@ -510,6 +544,9 @@ class WorkflowRunModel(Base):
     is_completed = Column(Boolean, default=False)
     recording_url = Column(String, nullable=True)
     transcript_url = Column(String, nullable=True)
+    extra = Column(
+        JSON, nullable=False, default=dict, server_default=text("'{}'::json")
+    )
     # Store storage backend as string enum (s3, minio)
     storage_backend = Column(
         Enum("s3", "minio", name="storage_backend"),
@@ -593,8 +630,9 @@ class WorkflowRunTextSessionModel(Base):
 
 class OrganizationUsageCycleModel(Base):
     """
-    This model is used to track the usage of Dograh tokens for an organization for a given usage
-    cycle.
+    This model is used to track reporting aggregates for an organization for a given
+    usage cycle. Quota fields on this model are deprecated; MPS owns quota and
+    credit ledger state.
     """
 
     __tablename__ = "organization_usage_cycles"
@@ -603,14 +641,24 @@ class OrganizationUsageCycleModel(Base):
     organization_id = Column(Integer, ForeignKey("organizations.id"), nullable=False)
     period_start = Column(DateTime(timezone=True), nullable=False)
     period_end = Column(DateTime(timezone=True), nullable=False)
-    quota_dograh_tokens = Column(Integer, nullable=False)
+    quota_dograh_tokens = Column(
+        Integer,
+        nullable=False,
+        comment="Deprecated. MPS owns quota and credit ledger state.",
+        info={"deprecated": True},
+    )
     used_dograh_tokens = Column(Float, nullable=False, default=0)
     total_duration_seconds = Column(
         Integer, nullable=False, default=0, server_default=text("0")
     )
     # New USD tracking fields
     used_amount_usd = Column(Float, nullable=True, default=0)
-    quota_amount_usd = Column(Float, nullable=True)
+    quota_amount_usd = Column(
+        Float,
+        nullable=True,
+        comment="Deprecated. MPS owns quota and credit ledger state.",
+        info={"deprecated": True},
+    )
     created_at = Column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
     updated_at = Column(
         DateTime(timezone=True),

api/db/organization_usage_client.py

@@ -10,6 +10,7 @@ from sqlalchemy.orm import joinedload
 from api.db.base_client import BaseDBClient
 from api.db.filters import apply_workflow_run_filters
 from api.db.models import (
+    OrganizationConfigurationModel,
     OrganizationModel,
     OrganizationUsageCycleModel,
     UserConfigurationModel,
@@ -17,11 +18,13 @@ from api.db.models import (
     WorkflowModel,
     WorkflowRunModel,
 )
-from api.schemas.user_configuration import UserConfiguration
+from api.enums import OrganizationConfigurationKey, UserConfigurationKey
+from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
+from api.utils.recording_artifacts import get_recording_storage_key
 
 
 class OrganizationUsageClient(BaseDBClient):
-    """Client for managing organization usage and quota operations."""
+    """Client for managing organization usage reporting aggregates."""
 
     async def get_or_create_current_cycle(
         self, organization_id: int, session=None
@@ -47,14 +50,7 @@ class OrganizationUsageClient(BaseDBClient):
         self, organization_id: int, session, commit: bool
     ) -> OrganizationUsageCycleModel:
         """Internal implementation for get_or_create_current_cycle."""
-        # Get organization to determine quota type
-        org_result = await session.execute(
-            select(OrganizationModel).where(OrganizationModel.id == organization_id)
-        )
-        org = org_result.scalar_one()
-
-        # Calculate current period
-        period_start, period_end = self._calculate_current_period(org)
+        period_start, period_end = self._calculate_current_period()
 
         # Try to get existing cycle
         cycle_result = await session.execute(
@@ -76,7 +72,8 @@ class OrganizationUsageClient(BaseDBClient):
             organization_id=organization_id,
             period_start=period_start,
             period_end=period_end,
-            quota_dograh_tokens=org.quota_dograh_tokens,
+            # Deprecated non-null column retained for historical schema compatibility.
+            quota_dograh_tokens=0,
         )
         # Handle concurrent inserts gracefully
         stmt = stmt.on_conflict_do_nothing(
@@ -100,95 +97,9 @@ class OrganizationUsageClient(BaseDBClient):
         )
         return cycle_result.scalar_one()
 
-    async def check_and_reserve_quota(
-        self, organization_id: int, estimated_tokens: int = 0
-    ) -> bool:
-        """
-        Check if organization has sufficient quota and optionally reserve tokens.
-        Returns True if quota is available, False otherwise.
-
-        This method is fully atomic and safe for concurrent access from multiple processes.
-        """
-        async with self.async_session() as session:
-            # Get organization
-            org_result = await session.execute(
-                select(OrganizationModel).where(OrganizationModel.id == organization_id)
-            )
-            org = org_result.scalar_one_or_none()
-
-            if not org or not org.quota_enabled:
-                # No quota enforcement if not enabled
-                return True
-
-            # Get or create current cycle within the same session/transaction
-            cycle = await self._get_or_create_current_cycle_impl(
-                organization_id, session, commit=False
-            )
-
-            # Atomic check and update with row-level lock
-            result = await session.execute(
-                select(OrganizationUsageCycleModel)
-                .where(
-                    and_(
-                        OrganizationUsageCycleModel.id == cycle.id,
-                        OrganizationUsageCycleModel.used_dograh_tokens
-                        + estimated_tokens
-                        <= OrganizationUsageCycleModel.quota_dograh_tokens,
-                    )
-                )
-                .with_for_update(skip_locked=False)
-            )
-
-            cycle_locked = result.scalar_one_or_none()
-            if cycle_locked:
-                # Update the usage atomically
-                cycle_locked.used_dograh_tokens += estimated_tokens
-                await session.commit()
-                return True
-
-            return False
-
-    async def update_usage_after_run(
-        self,
-        organization_id: int,
-        actual_tokens: float,
-        duration_seconds: float = 0,
-        charge_usd: float | None = None,
-    ) -> None:
-        """Update usage after a workflow run completes with actual token count and duration.
-
-        This method is fully atomic and safe for concurrent access from multiple processes.
-        """
-        async with self.async_session() as session:
-            # Get or create current cycle within the same session/transaction
-            cycle = await self._get_or_create_current_cycle_impl(
-                organization_id, session, commit=False
-            )
-
-            # Acquire a row-level lock for atomic update
-            result = await session.execute(
-                select(OrganizationUsageCycleModel)
-                .where(OrganizationUsageCycleModel.id == cycle.id)
-                .with_for_update(skip_locked=False)
-            )
-            cycle_locked = result.scalar_one()
-
-            # Update usage atomically
-            cycle_locked.used_dograh_tokens += actual_tokens
-            cycle_locked.total_duration_seconds += int(round(duration_seconds))
-
-            # Update USD amount if provided
-            if charge_usd is not None:
-                if cycle_locked.used_amount_usd is None:
-                    cycle_locked.used_amount_usd = 0
-                cycle_locked.used_amount_usd += charge_usd
-
-            await session.commit()
-
     async def get_current_usage(self, organization_id: int) -> dict:
-        """Get current period usage information."""
+        """Get current reporting-period usage information."""
         async with self.async_session() as session:
-            # Get organization
             org_result = await session.execute(
                 select(OrganizationModel).where(OrganizationModel.id == organization_id)
             )
@@ -199,42 +110,19 @@ class OrganizationUsageClient(BaseDBClient):
                 organization_id, session, commit=False
             )
 
-            # Calculate next refresh date
-            if org.quota_type == "monthly":
-                next_refresh = cycle.period_end + relativedelta(days=1)
-            else:  # annual
-                next_refresh = cycle.period_end + relativedelta(days=1)
-
             result = {
                 "period_start": cycle.period_start.isoformat(),
                 "period_end": cycle.period_end.isoformat(),
                 "used_dograh_tokens": cycle.used_dograh_tokens,
-                "quota_dograh_tokens": cycle.quota_dograh_tokens,
-                "percentage_used": (
-                    round(
-                        (cycle.used_dograh_tokens / cycle.quota_dograh_tokens) * 100, 2
-                    )
-                    if cycle.quota_dograh_tokens > 0
-                    else 0
-                ),
-                "next_refresh_date": next_refresh.date().isoformat(),
-                "quota_enabled": org.quota_enabled,
                 "total_duration_seconds": cycle.total_duration_seconds,
             }
 
             # Add USD fields if organization has pricing
             if org.price_per_second_usd is not None:
                 result["used_amount_usd"] = cycle.used_amount_usd or 0
-                result["quota_amount_usd"] = cycle.quota_amount_usd
                 result["currency"] = "USD"
                 result["price_per_second_usd"] = org.price_per_second_usd
 
-                # Calculate percentage based on USD if available
-                if cycle.quota_amount_usd and cycle.quota_amount_usd > 0:
-                    result["percentage_used"] = round(
-                        ((cycle.used_amount_usd or 0) / cycle.quota_amount_usd) * 100, 2
-                    )
-
             return result
 
     async def get_usage_history(
@@ -254,7 +142,7 @@ class OrganizationUsageClient(BaseDBClient):
                 .join(UserModel, WorkflowModel.user_id == UserModel.id)
                 .where(
                     UserModel.selected_organization_id == organization_id,
-                    WorkflowRunModel.cost_info.isnot(None),
+                    WorkflowRunModel.usage_info.isnot(None),
                 )
                 .order_by(WorkflowRunModel.created_at.desc())
             )
@@ -307,19 +195,8 @@ class OrganizationUsageClient(BaseDBClient):
             total_tokens = 0
             total_duration_seconds = 0
             for run in runs:
-                if run.cost_info:
-                    # Try to get dograh_token_usage first (new format)
-                    dograh_tokens = run.cost_info.get("dograh_token_usage", 0)
-                    # If not present, calculate from total_cost_usd (old format)
-                    if dograh_tokens == 0 and "total_cost_usd" in run.cost_info:
-                        dograh_tokens = round(
-                            float(run.cost_info["total_cost_usd"]) * 100, 2
-                        )
-                    # Get call duration
-                    call_duration = run.cost_info.get("call_duration_seconds", 0)
-                else:
-                    dograh_tokens = 0
-                    call_duration = 0
+                dograh_tokens = 0
+                call_duration = (run.usage_info or {}).get("call_duration_seconds", 0)
                 total_tokens += dograh_tokens
                 total_duration_seconds += int(round(call_duration))
 
@@ -350,6 +227,9 @@ class OrganizationUsageClient(BaseDBClient):
                     "call_duration_seconds": int(round(call_duration)),
                     "recording_url": run.recording_url,
                     "transcript_url": run.transcript_url,
+                    "user_recording_url": get_recording_storage_key(run.extra, "user"),
+                    "bot_recording_url": get_recording_storage_key(run.extra, "bot"),
+                    "extra": run.extra,
                     "public_access_token": run.public_access_token,
                     "phone_number": phone_number,
                     "caller_number": caller_number,
@@ -393,13 +273,14 @@ class OrganizationUsageClient(BaseDBClient):
                     WorkflowRunModel.initial_context,
                     WorkflowRunModel.gathered_context,
                     WorkflowRunModel.cost_info,
+                    WorkflowRunModel.usage_info,
                     WorkflowRunModel.public_access_token,
                 )
                 .join(WorkflowModel, WorkflowRunModel.workflow_id == WorkflowModel.id)
                 .join(UserModel, WorkflowModel.user_id == UserModel.id)
                 .where(
                     UserModel.selected_organization_id == organization_id,
-                    WorkflowRunModel.cost_info.isnot(None),
+                    WorkflowRunModel.usage_info.isnot(None),
                 )
                 .order_by(WorkflowRunModel.created_at.desc())
             )
@@ -440,21 +321,44 @@ class OrganizationUsageClient(BaseDBClient):
         """Get daily usage breakdown for an organization with pricing."""
 
         async with self.async_session() as session:
-            # Get user timezone if user_id is provided
+            # Get org timezone preference first, then fall back to legacy user config.
             user_timezone = "UTC"  # Default timezone
+            pref_result = await session.execute(
+                select(OrganizationConfigurationModel).where(
+                    OrganizationConfigurationModel.organization_id == organization_id,
+                    OrganizationConfigurationModel.key.in_(
+                        [
+                            OrganizationConfigurationKey.ORGANIZATION_PREFERENCES.value,
+                            OrganizationConfigurationKey.MODEL_CONFIGURATION_PREFERENCES.value,
+                        ]
+                    ),
+                )
+            )
+            pref_rows = pref_result.scalars().all()
+            pref_by_key = {pref.key: pref for pref in pref_rows}
+            pref_obj = pref_by_key.get(
+                OrganizationConfigurationKey.ORGANIZATION_PREFERENCES.value
+            ) or pref_by_key.get(
+                OrganizationConfigurationKey.MODEL_CONFIGURATION_PREFERENCES.value
+            )
+            if pref_obj and pref_obj.value:
+                user_timezone = pref_obj.value.get("timezone") or user_timezone
+
             if user_id:
                 config_result = await session.execute(
                     select(UserConfigurationModel).where(
-                        UserConfigurationModel.user_id == user_id
+                        UserConfigurationModel.user_id == user_id,
+                        UserConfigurationModel.key
+                        == UserConfigurationKey.MODEL_CONFIGURATION.value,
                     )
                 )
                 config_obj = config_result.scalar_one_or_none()
                 if config_obj and config_obj.configuration:
-                    user_config = UserConfiguration.model_validate(
+                    effective_config = EffectiveAIModelConfiguration.model_validate(
                         config_obj.configuration
                     )
-                    if user_config.timezone:
-                        user_timezone = user_config.timezone
+                    if effective_config.timezone and user_timezone == "UTC":
+                        user_timezone = effective_config.timezone
 
             # Validate timezone string
             try:
@@ -473,7 +377,7 @@ class OrganizationUsageClient(BaseDBClient):
                 select(
                     date_expr.label("date"),
                     func.sum(
-                        WorkflowRunModel.cost_info["call_duration_seconds"].as_float()
+                        WorkflowRunModel.usage_info["call_duration_seconds"].as_float()
                     ).label("total_seconds"),
                     func.count(WorkflowRunModel.id).label("call_count"),
                 )
@@ -522,83 +426,11 @@ class OrganizationUsageClient(BaseDBClient):
                 "currency": "USD",
             }
 
-    async def update_organization_quota(
-        self,
-        organization_id: int,
-        quota_type: str,
-        quota_dograh_tokens: int,
-        quota_reset_day: Optional[int] = None,
-        quota_start_date: Optional[datetime] = None,
-    ) -> OrganizationModel:
-        """Update organization quota settings."""
-        async with self.async_session() as session:
-            result = await session.execute(
-                select(OrganizationModel).where(OrganizationModel.id == organization_id)
-            )
-            org = result.scalar_one()
-
-            org.quota_type = quota_type
-            org.quota_dograh_tokens = quota_dograh_tokens
-            org.quota_enabled = True
-
-            if quota_type == "monthly" and quota_reset_day:
-                org.quota_reset_day = quota_reset_day
-            elif quota_type == "annual" and quota_start_date:
-                org.quota_start_date = quota_start_date
-
-            await session.commit()
-            await session.refresh(org)
-            return org
-
-    def _calculate_current_period(
-        self, org: OrganizationModel
-    ) -> tuple[datetime, datetime]:
-        """Calculate the current billing period based on organization settings."""
+    def _calculate_current_period(self) -> tuple[datetime, datetime]:
+        """Calculate the current calendar-month reporting period."""
         now = datetime.now(timezone.utc)
 
-        if org.quota_type == "monthly":
-            # Find the start of the current billing month
-            reset_day = org.quota_reset_day
-
-            # Handle month boundaries
-            if now.day >= reset_day:
-                period_start = now.replace(
-                    day=reset_day, hour=0, minute=0, second=0, microsecond=0
-                )
-            else:
-                # Previous month
-                period_start = (now - relativedelta(months=1)).replace(
-                    day=reset_day, hour=0, minute=0, second=0, microsecond=0
-                )
-
-            # End is one month later minus 1 second
-            period_end = (
-                period_start + relativedelta(months=1) - relativedelta(seconds=1)
-            )
-
-        else:  # annual
-            if not org.quota_start_date:
-                # Default to calendar year
-                period_start = now.replace(
-                    month=1, day=1, hour=0, minute=0, second=0, microsecond=0
-                )
-                period_end = (
-                    period_start + relativedelta(years=1) - relativedelta(seconds=1)
-                )
-            else:
-                # Find current annual period
-                start_date = org.quota_start_date.replace(tzinfo=timezone.utc)
-                years_diff = now.year - start_date.year
-
-                # Adjust for whether we've passed the anniversary
-                if now.month < start_date.month or (
-                    now.month == start_date.month and now.day < start_date.day
-                ):
-                    years_diff -= 1
-
-                period_start = start_date + relativedelta(years=years_diff)
-                period_end = (
-                    period_start + relativedelta(years=1) - relativedelta(seconds=1)
-                )
+        period_start = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+        period_end = period_start + relativedelta(months=1) - relativedelta(seconds=1)
 
         return period_start, period_end

api/db/user_client.py

@@ -8,7 +8,8 @@ from sqlalchemy.future import select
 
 from api.db.base_client import BaseDBClient
 from api.db.models import UserConfigurationModel, UserModel
-from api.schemas.user_configuration import UserConfiguration
+from api.enums import UserConfigurationKey
+from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
 
 
 class UserClient(BaseDBClient):
@@ -65,19 +66,56 @@ class UserClient(BaseDBClient):
             )
             return result.scalars().first()
 
-    async def get_user_configurations(self, user_id: int) -> UserConfiguration:
-        async with self.async_session() as session:
-            result = await session.execute(
-                select(UserConfigurationModel).where(
-                    UserConfigurationModel.user_id == user_id
-                )
+    async def _get_user_configuration_row(
+        self, session, user_id: int, key: str
+    ) -> UserConfigurationModel | None:
+        result = await session.execute(
+            select(UserConfigurationModel).where(
+                UserConfigurationModel.user_id == user_id,
+                UserConfigurationModel.key == key,
+            )
+        )
+        return result.scalars().first()
+
+    async def get_user_configuration_value(self, user_id: int, key: str) -> dict | None:
+        """Get the JSON value stored for a user under `key`, or None."""
+        async with self.async_session() as session:
+            row = await self._get_user_configuration_row(session, user_id, key)
+            return row.configuration if row else None
+
+    async def upsert_user_configuration_value(
+        self, user_id: int, key: str, value: dict
+    ) -> dict:
+        """Create or update the JSON value stored for a user under `key`."""
+        async with self.async_session() as session:
+            row = await self._get_user_configuration_row(session, user_id, key)
+            if row:
+                row.configuration = value
+            else:
+                row = UserConfigurationModel(
+                    user_id=user_id, key=key, configuration=value
+                )
+                session.add(row)
+            try:
+                await session.commit()
+            except Exception as e:
+                await session.rollback()
+                raise e
+            await session.refresh(row)
+            return row.configuration
+
+    async def get_user_configurations(
+        self, user_id: int
+    ) -> EffectiveAIModelConfiguration:
+        async with self.async_session() as session:
+            configuration_obj = await self._get_user_configuration_row(
+                session, user_id, UserConfigurationKey.MODEL_CONFIGURATION.value
             )
-            configuration_obj = result.scalars().first()
             if not configuration_obj:
-                return UserConfiguration()
+                return EffectiveAIModelConfiguration()
 
             try:
-                return UserConfiguration.model_validate(
+                return EffectiveAIModelConfiguration.model_validate(
                     {
                         **configuration_obj.configuration,
                         "last_validated_at": configuration_obj.last_validated_at,
@@ -90,41 +128,23 @@ class UserClient(BaseDBClient):
                     f"Failed to validate user configuration for user {user_id}: {e}. "
                     "Returning default configuration."
                 )
-                return UserConfiguration()
+                return EffectiveAIModelConfiguration()
 
     async def update_user_configuration(
-        self, user_id: int, configuration: UserConfiguration
-    ) -> UserConfiguration:
-        async with self.async_session() as session:
-            result = await session.execute(
-                select(UserConfigurationModel).where(
-                    UserConfigurationModel.user_id == user_id
-                )
-            )
-            configuration_obj = result.scalars().first()
-            if not configuration_obj:
-                configuration_obj = UserConfigurationModel(
-                    user_id=user_id, configuration=configuration.model_dump()
-                )
-                session.add(configuration_obj)
-            else:
-                configuration_obj.configuration = configuration.model_dump()
-            try:
-                await session.commit()
-            except Exception as e:
-                await session.rollback()
-                raise e
-            await session.refresh(configuration_obj)
-        return UserConfiguration.model_validate(configuration_obj.configuration)
+        self, user_id: int, configuration: EffectiveAIModelConfiguration
+    ) -> EffectiveAIModelConfiguration:
+        value = await self.upsert_user_configuration_value(
+            user_id,
+            UserConfigurationKey.MODEL_CONFIGURATION.value,
+            configuration.model_dump(),
+        )
+        return EffectiveAIModelConfiguration.model_validate(value)
 
     async def update_user_configuration_last_validated_at(self, user_id: int) -> None:
         async with self.async_session() as session:
-            result = await session.execute(
-                select(UserConfigurationModel).where(
-                    UserConfigurationModel.user_id == user_id
-                )
+            configuration_obj = await self._get_user_configuration_row(
+                session, user_id, UserConfigurationKey.MODEL_CONFIGURATION.value
             )
-            configuration_obj = result.scalars().first()
             if not configuration_obj:
                 raise ValueError(f"User configuration with ID {user_id} not found")
             configuration_obj.last_validated_at = datetime.now()

api/db/workflow_run_client.py

@@ -16,6 +16,8 @@ from api.db.models import (
 )
 from api.enums import CallType, StorageBackend
 from api.schemas.workflow import WorkflowRunResponseSchema
+from api.services.workflow.run_usage_response import format_public_cost_info
+from api.utils.recording_artifacts import get_recording_storage_key
 
 
 class WorkflowRunClient(BaseDBClient):
@@ -187,13 +189,19 @@ class WorkflowRunClient(BaseDBClient):
                         "workflow_name": run.workflow.name if run.workflow else None,
                         "user_id": run.workflow.user_id if run.workflow else None,
                         "organization_id": organization.id if organization else None,
-                        "organization_name": organization.provider_id
-                        if organization
-                        else None,
+                        "organization_name": (
+                            organization.provider_id if organization else None
+                        ),
                         "mode": run.mode,
                         "is_completed": run.is_completed,
                         "recording_url": run.recording_url,
                         "transcript_url": run.transcript_url,
+                        "user_recording_url": get_recording_storage_key(
+                            run.extra, "user"
+                        ),
+                        "bot_recording_url": get_recording_storage_key(
+                            run.extra, "bot"
+                        ),
                         "usage_info": run.usage_info,
                         "cost_info": run.cost_info,
                         "initial_context": run.initial_context,
@@ -312,26 +320,15 @@ class WorkflowRunClient(BaseDBClient):
                         "is_completed": run.is_completed,
                         "recording_url": run.recording_url,
                         "transcript_url": run.transcript_url,
-                        "cost_info": {
-                            "dograh_token_usage": (
-                                run.cost_info.get("dograh_token_usage")
-                                if run.cost_info
-                                and "dograh_token_usage" in run.cost_info
-                                else round(
-                                    float(run.cost_info.get("total_cost_usd", 0)) * 100,
-                                    2,
-                                )
-                                if run.cost_info and "total_cost_usd" in run.cost_info
-                                else 0
-                            ),
-                            "call_duration_seconds": int(
-                                round(run.cost_info.get("call_duration_seconds") or 0)
-                            )
-                            if run.cost_info
-                            else None,
-                        }
-                        if run.cost_info
-                        else None,
+                        "user_recording_url": get_recording_storage_key(
+                            run.extra, "user"
+                        ),
+                        "bot_recording_url": get_recording_storage_key(
+                            run.extra, "bot"
+                        ),
+                        "cost_info": format_public_cost_info(
+                            run.cost_info, run.usage_info
+                        ),
                         "definition_id": run.definition_id,
                         "initial_context": run.initial_context,
                         "gathered_context": run.gathered_context,
@@ -356,6 +353,7 @@ class WorkflowRunClient(BaseDBClient):
         logs: dict | None = None,
         state: str | None = None,
         annotations: dict | None = None,
+        extra: dict | None = None,
     ) -> WorkflowRunModel:
         async with self.async_session() as session:
             # Use SELECT FOR UPDATE to lock the row during the update
@@ -378,7 +376,12 @@ class WorkflowRunClient(BaseDBClient):
             if cost_info:
                 run.cost_info = cost_info
             if initial_context:
-                run.initial_context = initial_context
+                # Merge initial context patches so independent call-start/runtime
+                # writers do not erase keys stored earlier in the run lifecycle.
+                run.initial_context = {
+                    **(run.initial_context or {}),
+                    **initial_context,
+                }
             if gathered_context:
                 # Lets merge the incoming gathered context keys with the existing ones
                 run.gathered_context = {
@@ -390,6 +393,8 @@ class WorkflowRunClient(BaseDBClient):
                 run.logs = {**run.logs, **logs}
             if annotations:
                 run.annotations = {**run.annotations, **annotations}
+            if extra:
+                run.extra = {**run.extra, **extra}
             if is_completed:
                 run.is_completed = is_completed
             if state:

api/enums.py

@@ -89,6 +89,20 @@ class OrganizationConfigurationKey(Enum):
     LANGFUSE_CREDENTIALS = (
         "LANGFUSE_CREDENTIALS"  # Org-level Langfuse tracing credentials
     )
+    MODEL_CONFIGURATION_V2 = (
+        "MODEL_CONFIGURATION_V2"  # Org-level v2 AI model configuration
+    )
+    ORGANIZATION_PREFERENCES = "ORGANIZATION_PREFERENCES"  # Org-level defaults such as timezone/test call number
+    MODEL_CONFIGURATION_PREFERENCES = "MODEL_CONFIGURATION_PREFERENCES"  # Deprecated; read fallback for old org preferences
+
+
+class UserConfigurationKey(Enum):
+    """Keys for the per-user keyed JSON store (user_configurations)."""
+
+    MODEL_CONFIGURATION = (
+        "MODEL_CONFIGURATION"  # Legacy per-user v1 AI model configuration
+    )
+    ONBOARDING = "ONBOARDING"  # Post-signup onboarding state (gate, tooltips, actions)
 
 
 class WorkflowStatus(Enum):

api/pyproject.toml

@@ -1,5 +1,5 @@
 [project]
 name = "dograh-api"
-version = "1.34.0"
+version = "1.36.0"
 description = "Backend API for Dograh voice AI platform"
 requires-python = ">=3.13,<3.14"

api/requirements.txt

@@ -16,7 +16,7 @@ msgpack==1.1.2
 pgvector==0.4.2
 bcrypt==5.0.0
 email-validator==2.3.0
-posthog==7.11.1
+posthog==7.19.1
 fastmcp==3.2.4
 tuner-pipecat-sdk==0.2.0
 PyNaCl==1.6.2

api/routes/agent_stream.py

@@ -22,7 +22,7 @@ from starlette.websockets import WebSocketDisconnect
 
 from api.db import db_client
 from api.enums import CallType, WorkflowRunState
-from api.services.quota_service import check_dograh_quota_by_user_id
+from api.services.quota_service import authorize_workflow_run_start
 from api.services.telephony import registry as telephony_registry
 
 router = APIRouter(prefix="/agent-stream")
@@ -67,19 +67,6 @@ async def agent_stream_websocket(
         await websocket.close(code=1008, reason="Workflow not found")
         return
 
-    quota_result = await check_dograh_quota_by_user_id(
-        workflow.user_id, workflow_id=workflow.id
-    )
-    if not quota_result.has_quota:
-        logger.warning(
-            f"agent-stream quota exceeded for user {workflow.user_id}: "
-            f"{quota_result.error_message}"
-        )
-        await websocket.close(
-            code=1008, reason=quota_result.error_message or "Quota exceeded"
-        )
-        return
-
     numeric_suffix = int(str(uuid.uuid4()).replace("-", "")[:8], 16) % 100000000
     workflow_run_name = f"WR-AGS-{numeric_suffix:08d}"
     call_id = params.get("callId") or params.get("CallSid")
@@ -108,6 +95,20 @@ async def agent_stream_websocket(
     set_current_run_id(workflow_run.id)
     set_current_org_id(workflow.organization_id)
 
+    quota_result = await authorize_workflow_run_start(
+        workflow_id=workflow.id,
+        workflow_run_id=workflow_run.id,
+    )
+    if not quota_result.has_quota:
+        logger.warning(
+            f"agent-stream quota exceeded for user {workflow.user_id}: "
+            f"{quota_result.error_message}"
+        )
+        await websocket.close(
+            code=1008, reason=quota_result.error_message or "Quota exceeded"
+        )
+        return
+
     await db_client.update_workflow_run(
         run_id=workflow_run.id, state=WorkflowRunState.RUNNING.value
     )

api/routes/auth.py

@@ -3,9 +3,12 @@ from loguru import logger
 
 from api.db import db_client
 from api.db.models import UserModel
-from api.enums import PostHogEvent
+from api.enums import OrganizationConfigurationKey, PostHogEvent
 from api.schemas.auth import AuthResponse, LoginRequest, SignupRequest, UserResponse
 from api.services.auth.depends import create_user_configuration_with_mps_key, get_user
+from api.services.configuration.ai_model_configuration import (
+    convert_legacy_ai_model_configuration_to_v2,
+)
 from api.services.posthog_client import capture_event
 from api.utils.auth import create_jwt_token, hash_password, verify_password
 
@@ -47,6 +50,12 @@ async def signup(request: SignupRequest):
         )
         if mps_config:
             await db_client.update_user_configuration(user.id, mps_config)
+            model_config_v2 = convert_legacy_ai_model_configuration_to_v2(mps_config)
+            await db_client.upsert_configuration(
+                organization.id,
+                OrganizationConfigurationKey.MODEL_CONFIGURATION_V2.value,
+                model_config_v2.model_dump(mode="json", exclude_none=True),
+            )
     except Exception:
         logger.warning(
             "Failed to create default configuration for OSS user", exc_info=True

api/routes/campaign.py

@@ -18,7 +18,7 @@ from api.services.auth.depends import get_user
 from api.services.campaign.runner import campaign_runner_service
 from api.services.campaign.source_sync import CampaignSourceSyncService
 from api.services.campaign.source_sync_factory import get_sync_service
-from api.services.quota_service import check_dograh_quota
+from api.services.quota_service import authorize_workflow_run_start
 from api.services.reports import generate_campaign_report_csv
 from api.services.storage import storage_fs
 
@@ -550,7 +550,10 @@ async def start_campaign(
 
     # Check Dograh quota before starting campaign (apply per-workflow
     # model_overrides so we evaluate the keys this campaign will use).
-    quota_result = await check_dograh_quota(user, workflow_id=campaign.workflow_id)
+    quota_result = await authorize_workflow_run_start(
+        workflow_id=campaign.workflow_id,
+        actor_user=user,
+    )
     if not quota_result.has_quota:
         raise HTTPException(status_code=402, detail=quota_result.error_message)
 
@@ -872,7 +875,10 @@ async def resume_campaign(
 
     # Check Dograh quota before resuming campaign (apply per-workflow
     # model_overrides so we evaluate the keys this campaign will use).
-    quota_result = await check_dograh_quota(user, workflow_id=campaign.workflow_id)
+    quota_result = await authorize_workflow_run_start(
+        workflow_id=campaign.workflow_id,
+        actor_user=user,
+    )
     if not quota_result.has_quota:
         raise HTTPException(status_code=402, detail=quota_result.error_message)
 

api/routes/knowledge_base.py

@@ -369,6 +369,10 @@ async def search_chunks(
 
     try:
         # Import here to avoid circular dependency
+        from api.services.configuration.ai_model_configuration import (
+            apply_managed_embeddings_base_url,
+            get_resolved_ai_model_configuration,
+        )
         from api.services.configuration.registry import ServiceProviders
         from api.services.gen_ai import (
             AzureOpenAIEmbeddingService,
@@ -376,20 +380,29 @@ async def search_chunks(
         )
 
         # Try to get user's embeddings configuration
-        user_config = await db_client.get_user_configurations(user.id)
+        resolved_config = await get_resolved_ai_model_configuration(
+            user_id=user.id,
+            organization_id=user.selected_organization_id,
+        )
+        effective_config = resolved_config.effective
         embeddings_api_key = None
         embeddings_model = None
         embeddings_provider = None
+        embeddings_base_url = None
         embeddings_endpoint = None
         embeddings_api_version = None
 
-        if user_config.embeddings:
-            embeddings_api_key = user_config.embeddings.api_key
-            embeddings_model = user_config.embeddings.model
-            embeddings_provider = getattr(user_config.embeddings, "provider", None)
-            embeddings_endpoint = getattr(user_config.embeddings, "endpoint", None)
+        if effective_config.embeddings:
+            embeddings_api_key = effective_config.embeddings.api_key
+            embeddings_model = effective_config.embeddings.model
+            embeddings_provider = getattr(effective_config.embeddings, "provider", None)
+            embeddings_endpoint = getattr(effective_config.embeddings, "endpoint", None)
+            embeddings_base_url = apply_managed_embeddings_base_url(
+                provider=embeddings_provider,
+                base_url=getattr(effective_config.embeddings, "base_url", None),
+            )
             embeddings_api_version = getattr(
-                user_config.embeddings, "api_version", None
+                effective_config.embeddings, "api_version", None
             )
 
         # Initialize embedding service based on provider
@@ -406,9 +419,7 @@ async def search_chunks(
                 db_client=db_client,
                 api_key=embeddings_api_key,
                 model_id=embeddings_model or "text-embedding-3-small",
-                base_url=getattr(user_config.embeddings, "base_url", None)
-                if user_config.embeddings
-                else None,
+                base_url=embeddings_base_url,
             )
 
         # Perform search

api/routes/main.py

@@ -72,6 +72,11 @@ class HealthResponse(BaseModel):
     auth_provider: str
     turn_enabled: bool
     force_turn_relay: bool
+    # Public Stack Auth client config — only populated when auth_provider == "stack".
+    # The UI reads these at runtime to initialize Stack, so they no longer need to
+    # be baked into the browser bundle at build time. Both are public values.
+    stack_project_id: str | None = None
+    stack_publishable_client_key: str | None = None
 
 
 @router.get("/health", response_model=HealthResponse)
@@ -81,12 +86,15 @@ async def health() -> HealthResponse:
         AUTH_PROVIDER,
         DEPLOYMENT_MODE,
         FORCE_TURN_RELAY,
+        STACK_AUTH_PROJECT_ID,
+        STACK_PUBLISHABLE_CLIENT_KEY,
         TURN_SECRET,
     )
     from api.utils.common import get_backend_endpoints
 
     logger.debug("Health endpoint called")
     backend_endpoint, _ = await get_backend_endpoints()
+    is_stack = AUTH_PROVIDER == "stack"
     return HealthResponse(
         status="ok",
         version=APP_VERSION,
@@ -95,4 +103,8 @@ async def health() -> HealthResponse:
         auth_provider=AUTH_PROVIDER,
         turn_enabled=bool(TURN_SECRET),
         force_turn_relay=FORCE_TURN_RELAY,
+        stack_project_id=STACK_AUTH_PROJECT_ID if is_stack else None,
+        stack_publishable_client_key=(
+            STACK_PUBLISHABLE_CLIENT_KEY if is_stack else None
+        ),
     )

api/routes/organization.py

@@ -1,15 +1,27 @@
 from typing import List, Optional
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Query
 from loguru import logger
 from pydantic import BaseModel
 from sqlalchemy.exc import IntegrityError
 
-from api.constants import DEFAULT_CAMPAIGN_RETRY_CONFIG, DEFAULT_ORG_CONCURRENCY_LIMIT
+from api.constants import (
+    DEFAULT_CAMPAIGN_RETRY_CONFIG,
+    DEFAULT_ORG_CONCURRENCY_LIMIT,
+    DEPLOYMENT_MODE,
+)
 from api.db import db_client
 from api.db.models import UserModel
 from api.db.telephony_configuration_client import TelephonyConfigurationInUseError
 from api.enums import OrganizationConfigurationKey, PostHogEvent
+from api.schemas.ai_model_configuration import (
+    DOGRAH_DEFAULT_LANGUAGE,
+    DOGRAH_DEFAULT_VOICE,
+    DOGRAH_SPEED_OPTIONS,
+    OrganizationAIModelConfigurationResponse,
+    OrganizationAIModelConfigurationV2,
+)
+from api.schemas.organization_preferences import OrganizationPreferences
 from api.schemas.telephony_config import (
     TelephonyConfigRequest,
     TelephonyConfigurationCreateRequest,
@@ -26,8 +38,37 @@ from api.schemas.telephony_phone_number import (
     PhoneNumberUpdateRequest,
     ProviderSyncStatus,
 )
-from api.services.auth.depends import get_user
-from api.services.configuration.masking import is_mask_of, mask_key
+from api.services.auth.depends import get_user, get_user_with_selected_organization
+from api.services.configuration.ai_model_configuration import (
+    check_for_masked_keys_in_ai_model_configuration_v2,
+    compile_ai_model_configuration_v2,
+    convert_legacy_ai_model_configuration_to_v2,
+    get_organization_ai_model_configuration_v2,
+    get_resolved_ai_model_configuration,
+    mask_ai_model_configuration_v2,
+    merge_ai_model_configuration_v2_secrets,
+    migrate_workflow_model_configurations_to_v2,
+    upsert_organization_ai_model_configuration_v2,
+)
+from api.services.configuration.check_validity import UserConfigurationValidator
+from api.services.configuration.defaults import DEFAULT_SERVICE_PROVIDERS
+from api.services.configuration.masking import is_mask_of, mask_key, mask_user_config
+from api.services.configuration.registry import (
+    DOGRAH_STT_LANGUAGES,
+    REGISTRY,
+    DograhTTSService,
+    ServiceProviders,
+    ServiceType,
+)
+from api.services.mps_billing import ensure_hosted_mps_billing_account_v2
+from api.services.organization_context import (
+    OrganizationContextResponse,
+    get_organization_context,
+)
+from api.services.organization_preferences import (
+    get_organization_preferences,
+    upsert_organization_preferences,
+)
 from api.services.posthog_client import capture_event
 from api.services.telephony import registry as telephony_registry
 from api.services.telephony.factory import get_telephony_provider_by_id
@@ -98,6 +139,12 @@ class TelephonyConfigWarningsResponse(BaseModel):
     telnyx_missing_webhook_public_key_count: int
 
 
+@router.get("/context", response_model=OrganizationContextResponse)
+async def get_current_organization_context(user: UserModel = Depends(get_user)):
+    """Return organization-scoped configuration signals owned by Dograh."""
+    return await get_organization_context(user)
+
+
 @router.get(
     "/telephony-providers/metadata",
     response_model=TelephonyProvidersMetadataResponse,
@@ -159,6 +206,247 @@ async def get_telephony_config_warnings(user: UserModel = Depends(get_user)):
     )
 
 
+# ---------------------------------------------------------------------------
+# AI model configurations v2
+# ---------------------------------------------------------------------------
+
+
+def _dograh_allows_custom_voice() -> bool:
+    extra = DograhTTSService.model_fields["voice"].json_schema_extra
+    if isinstance(extra, dict):
+        return bool(extra.get("allow_custom_input", False))
+    return False
+
+
+def _byok_provider_schemas(service_type: ServiceType) -> dict[str, dict]:
+    return {
+        provider: model_cls.model_json_schema()
+        for provider, model_cls in REGISTRY[service_type].items()
+        if provider != ServiceProviders.DOGRAH.value
+    }
+
+
+async def _model_configuration_v2_response(
+    *,
+    user: UserModel,
+    configuration: OrganizationAIModelConfigurationV2 | None = None,
+) -> OrganizationAIModelConfigurationResponse:
+    resolved = await get_resolved_ai_model_configuration(
+        user_id=user.id,
+        organization_id=user.selected_organization_id,
+    )
+    raw_configuration = (
+        configuration
+        if configuration is not None
+        else resolved.organization_configuration
+    )
+    return OrganizationAIModelConfigurationResponse(
+        configuration=mask_ai_model_configuration_v2(raw_configuration),
+        effective_configuration=mask_user_config(resolved.effective),
+        source=resolved.source,
+    )
+
+
+@router.get("/model-configurations/v2/defaults")
+async def get_model_configuration_v2_defaults(
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    byok_default_providers = {
+        service: provider
+        for service, provider in DEFAULT_SERVICE_PROVIDERS.items()
+        if provider != ServiceProviders.DOGRAH.value
+    }
+    return {
+        "dograh": {
+            "voices": [DOGRAH_DEFAULT_VOICE],
+            "allow_custom_input": _dograh_allows_custom_voice(),
+            "speeds": list(DOGRAH_SPEED_OPTIONS),
+            "languages": DOGRAH_STT_LANGUAGES,
+            "defaults": {
+                "voice": DOGRAH_DEFAULT_VOICE,
+                "speed": 1.0,
+                "language": DOGRAH_DEFAULT_LANGUAGE,
+            },
+        },
+        "byok": {
+            "pipeline": {
+                "llm": _byok_provider_schemas(ServiceType.LLM),
+                "tts": _byok_provider_schemas(ServiceType.TTS),
+                "stt": _byok_provider_schemas(ServiceType.STT),
+                "embeddings": _byok_provider_schemas(ServiceType.EMBEDDINGS),
+                "default_providers": byok_default_providers,
+            },
+            "realtime": {
+                "realtime": _byok_provider_schemas(ServiceType.REALTIME),
+                "llm": _byok_provider_schemas(ServiceType.LLM),
+                "embeddings": _byok_provider_schemas(ServiceType.EMBEDDINGS),
+                "default_providers": byok_default_providers,
+            },
+        },
+    }
+
+
+@router.get(
+    "/model-configurations/v2",
+    response_model=OrganizationAIModelConfigurationResponse,
+)
+async def get_model_configuration_v2(
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    return await _model_configuration_v2_response(user=user)
+
+
+@router.put(
+    "/model-configurations/v2",
+    response_model=OrganizationAIModelConfigurationResponse,
+)
+async def save_model_configuration_v2(
+    request: OrganizationAIModelConfigurationV2,
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    organization_id = user.selected_organization_id
+    existing = await get_organization_ai_model_configuration_v2(organization_id)
+    configuration = merge_ai_model_configuration_v2_secrets(request, existing)
+    try:
+        check_for_masked_keys_in_ai_model_configuration_v2(configuration)
+        effective = compile_ai_model_configuration_v2(configuration)
+        await UserConfigurationValidator().validate(
+            effective,
+            organization_id=organization_id,
+            created_by=user.provider_id,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=exc.args[0])
+
+    await upsert_organization_ai_model_configuration_v2(
+        organization_id,
+        configuration,
+    )
+    return await _model_configuration_v2_response(
+        user=user,
+        configuration=configuration,
+    )
+
+
+@router.get("/model-configurations/v2/migration-preview")
+async def preview_model_configuration_v2_migration(
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    legacy = await db_client.get_user_configurations(user.id)
+    try:
+        configuration = convert_legacy_ai_model_configuration_to_v2(legacy)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))
+    return {
+        "configuration": mask_ai_model_configuration_v2(configuration),
+        "effective_configuration": mask_user_config(
+            compile_ai_model_configuration_v2(configuration)
+        ),
+    }
+
+
+@router.post(
+    "/model-configurations/v2/migrate",
+    response_model=OrganizationAIModelConfigurationResponse,
+)
+async def migrate_model_configuration_v2(
+    force: bool = Query(default=False),
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    organization_id = user.selected_organization_id
+    existing = await get_organization_ai_model_configuration_v2(organization_id)
+    if existing is not None and not force:
+        raise HTTPException(
+            status_code=409,
+            detail="Organization already has a v2 model configuration",
+        )
+
+    legacy = await db_client.get_user_configurations(user.id)
+    try:
+        configuration = convert_legacy_ai_model_configuration_to_v2(legacy)
+        effective = compile_ai_model_configuration_v2(configuration)
+        await UserConfigurationValidator().validate(
+            effective,
+            organization_id=organization_id,
+            created_by=user.provider_id,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=exc.args[0])
+
+    if DEPLOYMENT_MODE != "oss":
+        try:
+            await ensure_hosted_mps_billing_account_v2(
+                organization_id,
+                created_by=str(user.provider_id),
+            )
+        except Exception as exc:
+            logger.error(
+                "Failed to initialize MPS billing v2 account for organization {}: {}",
+                organization_id,
+                exc,
+            )
+            raise HTTPException(
+                status_code=502,
+                detail="Failed to initialize MPS billing v2 account",
+            )
+
+    await upsert_organization_ai_model_configuration_v2(
+        organization_id,
+        configuration,
+    )
+    await migrate_workflow_model_configurations_to_v2(
+        organization_id=organization_id,
+        fallback_user_config=legacy,
+    )
+    return await _model_configuration_v2_response(
+        user=user,
+        configuration=configuration,
+    )
+
+
+@router.get("/preferences", response_model=OrganizationPreferences)
+async def get_preferences(
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    organization_id = user.selected_organization_id
+    return await get_organization_preferences(organization_id)
+
+
+@router.put("/preferences", response_model=OrganizationPreferences)
+async def save_preferences(
+    request: OrganizationPreferences,
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    organization_id = user.selected_organization_id
+    return await upsert_organization_preferences(
+        organization_id,
+        request,
+    )
+
+
+@router.get(
+    "/model-configurations/preferences",
+    response_model=OrganizationPreferences,
+    include_in_schema=False,
+)
+async def get_model_configuration_preferences_legacy(
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    return await get_preferences(user=user)
+
+
+@router.put(
+    "/model-configurations/preferences",
+    response_model=OrganizationPreferences,
+    include_in_schema=False,
+)
+async def save_model_configuration_preferences_legacy(
+    request: OrganizationPreferences,
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    return await save_preferences(request=request, user=user)
+
+
 def preserve_masked_fields(provider: str, request_dict: dict, existing: dict):
     """If the client re-submitted a masked sensitive field, restore the original."""
     for field_name in _sensitive_fields(provider):

api/routes/organization_usage.py

@@ -1,19 +1,20 @@
 import json
 from datetime import datetime, timedelta
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Literal, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 from fastapi.responses import StreamingResponse
 from loguru import logger
 from pydantic import BaseModel, Field
 
-from api.constants import DEPLOYMENT_MODE
+from api.constants import DEPLOYMENT_MODE, UI_APP_URL
 from api.db import db_client
 from api.db.models import UserModel
-from api.services.auth.depends import get_user
+from api.services.auth.depends import get_user, get_user_with_selected_organization
 from api.services.mps_service_key_client import mps_service_key_client
 from api.services.reports import generate_usage_runs_report_csv
 from api.utils.artifacts import artifact_url
+from api.utils.recording_artifacts import has_recording_track
 
 router = APIRouter(prefix="/organizations")
 
@@ -22,14 +23,8 @@ class CurrentUsageResponse(BaseModel):
     period_start: str
     period_end: str
     used_dograh_tokens: float
-    quota_dograh_tokens: int
-    percentage_used: float
-    next_refresh_date: str
-    quota_enabled: bool
     total_duration_seconds: int
-    # New USD fields
     used_amount_usd: Optional[float] = None
-    quota_amount_usd: Optional[float] = None
     currency: Optional[str] = None
     price_per_second_usd: Optional[float] = None
 
@@ -40,6 +35,61 @@ class MPSCreditsResponse(BaseModel):
     total_quota: float
 
 
+class MPSCreditPurchaseUrlResponse(BaseModel):
+    checkout_url: str
+
+
+class MPSBillingAccountResponse(BaseModel):
+    id: int
+    organization_id: int
+    billing_mode: str
+    cached_balance_credits: float
+    currency: str
+
+
+class MPSCreditLedgerEntryResponse(BaseModel):
+    id: int
+    entry_type: str
+    origin: Optional[str] = None
+    credits_delta: float
+    balance_after: float
+    amount_minor: Optional[int] = None
+    amount_currency: Optional[str] = None
+    payment_order_id: Optional[int] = None
+    metric_code: Optional[str] = None
+    correlation_id: Optional[str] = None
+    aggregation_key: Optional[str] = None
+    usage_event_id: Optional[int] = None
+    workflow_run_id: Optional[int] = None
+    workflow_id: Optional[int] = None
+    billable_quantity: Optional[float] = None
+    quantity_unit: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: str
+
+
+class MPSBillingCreditsResponse(BaseModel):
+    billing_version: Literal["legacy", "v2"]
+    total_credits_used: float = 0.0
+    remaining_credits: float = 0.0
+    total_quota: float = 0.0
+    account: Optional[MPSBillingAccountResponse] = None
+    ledger_entries: List[MPSCreditLedgerEntryResponse] = Field(default_factory=list)
+    total_count: int = 0
+    page: int = 1
+    limit: int = 50
+    total_pages: int = 0
+
+
+def _optional_int(value: Any) -> Optional[int]:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
 class WorkflowRunUsageResponse(BaseModel):
     id: int
     workflow_id: int
@@ -50,8 +100,12 @@ class WorkflowRunUsageResponse(BaseModel):
     call_duration_seconds: int
     recording_url: Optional[str] = None
     transcript_url: Optional[str] = None
+    user_recording_url: Optional[str] = None
+    bot_recording_url: Optional[str] = None
     recording_public_url: Optional[str] = None
     transcript_public_url: Optional[str] = None
+    user_recording_public_url: Optional[str] = None
+    bot_recording_public_url: Optional[str] = None
     public_access_token: Optional[str] = None
     phone_number: Optional[str] = Field(
         default=None,
@@ -97,7 +151,7 @@ class DailyUsageBreakdownResponse(BaseModel):
 
 @router.get("/usage/current-period", response_model=CurrentUsageResponse)
 async def get_current_period_usage(user: UserModel = Depends(get_user)):
-    """Get current billing period usage for the user's organization."""
+    """Get current reporting-period usage for the user's organization."""
     if not user.selected_organization_id:
         raise HTTPException(status_code=400, detail="No organization selected")
 
@@ -142,6 +196,206 @@ async def get_mps_credits(user: UserModel = Depends(get_user)):
         raise HTTPException(status_code=500, detail=str(e))
 
 
+async def _get_mps_billing_account_status(
+    user: UserModel, organization_id: int
+) -> Optional[dict]:
+    return await mps_service_key_client.get_billing_account_status(
+        organization_id=organization_id,
+        created_by=str(user.provider_id),
+    )
+
+
+def _is_mps_billing_v2(account: Optional[dict]) -> bool:
+    return bool(account and account.get("billing_mode") == "v2")
+
+
+async def _legacy_mps_credits_response(user: UserModel) -> MPSBillingCreditsResponse:
+    if DEPLOYMENT_MODE == "oss":
+        usage = await mps_service_key_client.get_usage_by_created_by(
+            str(user.provider_id)
+        )
+    else:
+        if not user.selected_organization_id:
+            raise HTTPException(status_code=400, detail="No organization selected")
+        usage = await mps_service_key_client.get_usage_by_organization(
+            user.selected_organization_id
+        )
+
+    total_used = float(usage.get("total_credits_used", 0.0))
+    total_remaining = float(usage.get("remaining_credits", 0.0))
+    return MPSBillingCreditsResponse(
+        billing_version="legacy",
+        total_credits_used=total_used,
+        remaining_credits=total_remaining,
+        total_quota=total_used + total_remaining,
+    )
+
+
+@router.get("/billing/credits", response_model=MPSBillingCreditsResponse)
+async def get_billing_credits(
+    page: int = Query(1, ge=1),
+    limit: int = Query(50, ge=1, le=100),
+    user: UserModel = Depends(get_user),
+):
+    """Return legacy MPS credits or paginated v2 billing ledger details for the org."""
+    try:
+        if DEPLOYMENT_MODE == "oss" or not user.selected_organization_id:
+            return await _legacy_mps_credits_response(user)
+
+        organization_id = user.selected_organization_id
+        account_status = await _get_mps_billing_account_status(user, organization_id)
+        if not _is_mps_billing_v2(account_status):
+            return await _legacy_mps_credits_response(user)
+
+        ledger = await mps_service_key_client.get_credit_ledger(
+            organization_id=organization_id,
+            page=page,
+            limit=limit,
+            created_by=str(user.provider_id),
+        )
+        account = ledger.get("account") or {}
+        ledger_entries = ledger.get("ledger_entries") or []
+        total_count = int(ledger.get("total_count") or len(ledger_entries))
+        response_limit = int(ledger.get("limit") or limit)
+        total_pages = int(
+            ledger.get("total_pages")
+            or ((total_count + response_limit - 1) // response_limit)
+        )
+        workflow_ids_by_run_id: dict[int, int] = {}
+        workflow_run_ids = {
+            workflow_run_id
+            for entry in ledger_entries
+            if (workflow_run_id := _optional_int(entry.get("workflow_run_id")))
+            is not None
+        }
+        for workflow_run_id in workflow_run_ids:
+            workflow_run = await db_client.get_workflow_run_by_id(workflow_run_id)
+            if (
+                workflow_run
+                and workflow_run.workflow
+                and workflow_run.workflow.organization_id == organization_id
+            ):
+                workflow_ids_by_run_id[workflow_run_id] = workflow_run.workflow_id
+
+        balance = float(account.get("cached_balance_credits") or 0.0)
+        total_debits = sum(
+            abs(float(entry.get("credits_delta") or 0.0))
+            for entry in ledger_entries
+            if float(entry.get("credits_delta") or 0.0) < 0
+        )
+        if ledger.get("total_debits_credits") is not None:
+            total_debits = float(ledger["total_debits_credits"])
+
+        return MPSBillingCreditsResponse(
+            billing_version="v2",
+            total_credits_used=total_debits,
+            remaining_credits=balance,
+            total_quota=balance + total_debits,
+            account=MPSBillingAccountResponse(
+                id=int(account["id"]),
+                organization_id=int(account["organization_id"]),
+                billing_mode=str(account["billing_mode"]),
+                cached_balance_credits=balance,
+                currency=str(account.get("currency") or "USD"),
+            ),
+            ledger_entries=[
+                MPSCreditLedgerEntryResponse(
+                    id=int(entry["id"]),
+                    entry_type=str(entry["entry_type"]),
+                    origin=entry.get("origin"),
+                    credits_delta=float(entry.get("credits_delta") or 0.0),
+                    balance_after=float(entry.get("balance_after") or 0.0),
+                    amount_minor=entry.get("amount_minor"),
+                    amount_currency=entry.get("amount_currency"),
+                    payment_order_id=entry.get("payment_order_id"),
+                    metric_code=entry.get("metric_code"),
+                    correlation_id=entry.get("correlation_id"),
+                    aggregation_key=entry.get("aggregation_key"),
+                    usage_event_id=_optional_int(entry.get("usage_event_id")),
+                    workflow_run_id=_optional_int(entry.get("workflow_run_id")),
+                    workflow_id=(
+                        workflow_ids_by_run_id.get(
+                            _optional_int(entry.get("workflow_run_id"))
+                        )
+                        if entry.get("workflow_run_id") is not None
+                        else None
+                    ),
+                    billable_quantity=(
+                        float(entry["billable_quantity"])
+                        if entry.get("billable_quantity") is not None
+                        else None
+                    ),
+                    quantity_unit=entry.get("quantity_unit"),
+                    metadata=entry.get("metadata") or {},
+                    created_at=str(entry["created_at"]),
+                )
+                for entry in ledger_entries
+            ],
+            total_count=total_count,
+            page=int(ledger.get("page") or page),
+            limit=response_limit,
+            total_pages=total_pages,
+        )
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"Failed to fetch billing credits: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post(
+    "/usage/mps-credits/purchase-url",
+    response_model=MPSCreditPurchaseUrlResponse,
+)
+async def create_mps_credit_purchase_url(
+    user: UserModel = Depends(get_user_with_selected_organization),
+):
+    """Create a checkout URL for organizations using Dograh-managed MPS v2."""
+    if DEPLOYMENT_MODE == "oss":
+        raise HTTPException(
+            status_code=404,
+            detail="Credit purchases are not available in OSS mode",
+        )
+
+    organization_id = user.selected_organization_id
+    assert organization_id is not None
+    account_status = await _get_mps_billing_account_status(user, organization_id)
+    if not _is_mps_billing_v2(account_status):
+        raise HTTPException(
+            status_code=403,
+            detail=(
+                "Credit purchases are available only for organizations using billing v2"
+            ),
+        )
+
+    try:
+        session = await mps_service_key_client.create_credit_purchase_url(
+            organization_id=organization_id,
+            created_by=str(user.provider_id),
+            return_url=f"{UI_APP_URL.rstrip('/')}/billing",
+            billing_details={
+                "source": "dograh_billing",
+                "dograh_user_id": str(user.id),
+                "dograh_provider_id": str(user.provider_id),
+            },
+        )
+    except Exception as exc:
+        logger.error(f"Failed to create MPS credit purchase URL: {exc}")
+        raise HTTPException(
+            status_code=502,
+            detail="Failed to create credit purchase URL",
+        )
+
+    checkout_url = session.get("checkout_url")
+    if not checkout_url:
+        logger.error(f"MPS checkout session response missing checkout_url: {session}")
+        raise HTTPException(
+            status_code=502,
+            detail="MPS checkout session response missing checkout_url",
+        )
+    return MPSCreditPurchaseUrlResponse(checkout_url=checkout_url)
+
+
 FILTERS_DESCRIPTION = """\
 JSON-encoded array of filter objects. Each object has the shape:
 
@@ -233,6 +487,17 @@ async def get_usage_history(
                 public_access_token, "transcript"
             )
             run["recording_public_url"] = artifact_url(public_access_token, "recording")
+            run["user_recording_public_url"] = (
+                artifact_url(public_access_token, "user_recording")
+                if has_recording_track(run.get("extra"), "user")
+                else None
+            )
+            run["bot_recording_public_url"] = (
+                artifact_url(public_access_token, "bot_recording")
+                if has_recording_track(run.get("extra"), "bot")
+                else None
+            )
+            run.pop("extra", None)
 
         return {
             "runs": runs,

api/routes/public_agent.py

@@ -14,7 +14,7 @@ from pydantic import BaseModel
 
 from api.db import db_client
 from api.enums import TriggerState, WorkflowStatus
-from api.services.quota_service import check_dograh_quota_by_user_id
+from api.services.quota_service import authorize_workflow_run_start
 from api.services.telephony.factory import (
     get_default_telephony_provider,
     get_telephony_provider_by_id,
@@ -179,14 +179,6 @@ async def _execute_resolved_target(
     """Shared execution path once the target workflow has been resolved."""
     execution_user_id = _get_execution_user_id(target.workflow)
 
-    # Check Dograh quota using the workflow owner's config and model overrides.
-    quota_result = await check_dograh_quota_by_user_id(
-        execution_user_id,
-        workflow_id=target.workflow.id,
-    )
-    if not quota_result.has_quota:
-        raise HTTPException(status_code=402, detail=quota_result.error_message)
-
     # Get telephony provider — either the caller-specified config (validated
     # against the workflow's org) or the org's default config.
     if request.telephony_configuration_id is not None:
@@ -268,6 +260,15 @@ async def _execute_resolved_target(
         f"to phone number {request.phone_number}"
     )
 
+    # Check Dograh quota after the run exists so hosted v2 can mint and store
+    # the MPS correlation id before the provider starts the call.
+    quota_result = await authorize_workflow_run_start(
+        workflow_id=target.workflow.id,
+        workflow_run_id=workflow_run.id,
+    )
+    if not quota_result.has_quota:
+        raise HTTPException(status_code=402, detail=quota_result.error_message)
+
     # 9. Construct webhook URL for telephony provider callback
     backend_endpoint, _ = await get_backend_endpoints()
     webhook_endpoint = provider.WEBHOOK_ENDPOINT

api/routes/public_download.py

@@ -6,14 +6,16 @@ post-call processing for runs that execute integrations, QA, or campaign
 reporting.
 """
 
-from typing import Literal
-
 from fastapi import APIRouter, HTTPException, Query
 from fastapi.responses import RedirectResponse
 from loguru import logger
 
 from api.db import db_client
 from api.services.storage import get_storage_for_backend
+from api.utils.recording_artifacts import (
+    get_recording_storage_backend,
+    get_recording_storage_key,
+)
 
 router = APIRouter(prefix="/public/download")
 
@@ -21,7 +23,7 @@ router = APIRouter(prefix="/public/download")
 @router.get("/workflow/{token}/{artifact_type}")
 async def download_workflow_artifact(
     token: str,
-    artifact_type: Literal["recording", "transcript"],
+    artifact_type: str,
     inline: bool = Query(
         default=False, description="Display inline in browser instead of download"
     ),
@@ -36,13 +38,15 @@ async def download_workflow_artifact(
 
     Args:
         token: The public access token (UUID format)
-        artifact_type: Type of artifact - "recording" or "transcript"
+        artifact_type: Type of artifact - "recording", "transcript",
+            "user_recording", or "bot_recording"
         inline: If true, sets Content-Disposition to inline for browser preview
 
     Returns:
         RedirectResponse to the signed URL (302 redirect)
 
     Raises:
+        HTTPException 400: If artifact type is unsupported
         HTTPException 404: If token is invalid or artifact not found
     """
     # 1. Lookup workflow run by token
@@ -52,10 +56,26 @@ async def download_workflow_artifact(
         raise HTTPException(status_code=404, detail="Invalid or expired token")
 
     # 2. Get file path based on artifact type
+    artifact_storage_backend = None
     if artifact_type == "recording":
         file_path = workflow_run.recording_url
-    else:  # transcript
+    elif artifact_type == "transcript":
         file_path = workflow_run.transcript_url
+    elif artifact_type == "user_recording":
+        file_path = get_recording_storage_key(workflow_run.extra, "user")
+        artifact_storage_backend = get_recording_storage_backend(
+            workflow_run.extra, "user"
+        )
+    elif artifact_type == "bot_recording":
+        file_path = get_recording_storage_key(workflow_run.extra, "bot")
+        artifact_storage_backend = get_recording_storage_backend(
+            workflow_run.extra, "bot"
+        )
+    else:
+        logger.warning(
+            f"Unsupported artifact type: type={artifact_type}, workflow_run_id={workflow_run.id}"
+        )
+        raise HTTPException(status_code=400, detail="Unsupported artifact type")
 
     if not file_path:
         logger.warning(
@@ -68,7 +88,9 @@ async def download_workflow_artifact(
 
     # 3. Get storage backend for this workflow run
     try:
-        storage = get_storage_for_backend(workflow_run.storage_backend)
+        storage = get_storage_for_backend(
+            artifact_storage_backend or workflow_run.storage_backend
+        )
     except ValueError as e:
         logger.error(f"Invalid storage backend: {workflow_run.storage_backend}")
         raise HTTPException(status_code=500, detail="Storage configuration error")

api/routes/s3_signed_url.py

@@ -40,14 +40,22 @@ class PresignedUploadUrlResponse(BaseModel):
 router = APIRouter(prefix="/s3", tags=["s3"])
 
 
+ORG_SCOPED_STORAGE_PREFIXES = ("campaigns", "knowledge_base")
+
+
 def _extract_org_id_from_key(key: str) -> Optional[int]:
     """Try to extract an organization ID from a storage key.
 
-    Matches keys of the form ``{prefix}/{org_id}/...`` where *org_id* is a
-    positive integer.  Returns ``None`` when the pattern does not match.
+    Matches known org-scoped keys of the form ``{prefix}/{org_id}/...`` where
+    *org_id* is a positive integer. Returns ``None`` when the pattern does not
+    match.
     """
     parts = key.split("/")
-    if len(parts) >= 3 and parts[1].isdigit():
+    if (
+        len(parts) >= 3
+        and parts[0] in ORG_SCOPED_STORAGE_PREFIXES
+        and parts[1].isdigit()
+    ):
         return int(parts[1])
     return None
 
@@ -58,15 +66,20 @@ def _extract_legacy_workflow_run_id(key: str) -> Optional[int]:
     Supports:
       - ``transcripts/{run_id}.txt``
       - ``recordings/{run_id}.wav``
+      - ``recordings/{run_id}/user.wav``
+      - ``recordings/{run_id}/bot.wav``
 
     Returns ``None`` when the key does not match a legacy pattern.
     """
     if key.startswith("transcripts/") and key.endswith(".txt"):
         run_id_str = key[len("transcripts/") : -4]
-    elif key.startswith("recordings/") and key.endswith(".wav"):
-        run_id_str = key[len("recordings/") : -4]
     else:
-        return None
+        recording_match = re.fullmatch(
+            r"recordings/(\d+)(?:\.wav|/(?:user|bot)\.wav)", key
+        )
+        if not recording_match:
+            return None
+        run_id_str = recording_match.group(1)
 
     return int(run_id_str) if run_id_str.isdigit() else None
 
@@ -89,8 +102,13 @@ async def _validate_and_extract_workflow_run_id(
     """
     if key.startswith("transcripts/") and key.endswith(".txt"):
         run_id_str = key[len("transcripts/") : -4]  # strip prefix & suffix
-    elif key.startswith("recordings/") and key.endswith(".wav"):
-        run_id_str = key[len("recordings/") : -4]
+    elif key.startswith("recordings/"):
+        run_id = _extract_legacy_workflow_run_id(key)
+        if run_id is None:
+            raise HTTPException(
+                status_code=400, detail="Invalid workflow_run_id in key"
+            )
+        return run_id
     elif allow_special_paths and key.startswith("voicemail_detections/"):
         return None  # Skip validation for these paths
     else:
@@ -159,9 +177,9 @@ async def get_signed_url(
     """Return a short-lived signed URL for a file stored on S3 / MinIO.
 
     Access Control:
-    * Keys that embed an organization ID (``{prefix}/{org_id}/...``) are
-      authorized by matching the org_id against the requesting user's
-      organization.
+    * Known org-scoped keys (for example ``campaigns/{org_id}/...`` and
+      ``knowledge_base/{org_id}/...``) are authorized by matching the org_id
+      against the requesting user's organization.
     * Legacy keys (``recordings/{run_id}.wav``, ``transcripts/{run_id}.txt``)
       are authorized via the workflow run they belong to.
     * Superusers can request any key.

api/routes/telephony.py

@@ -25,7 +25,7 @@ from api.enums import CallType, WorkflowRunState
 from api.errors.telephony_errors import TelephonyError
 from api.sdk_expose import sdk_expose
 from api.services.auth.depends import get_user
-from api.services.quota_service import check_dograh_quota_by_user_id
+from api.services.quota_service import authorize_workflow_run_start
 from api.services.telephony.call_transfer_manager import get_call_transfer_manager
 from api.services.telephony.factory import (
     get_all_telephony_providers,
@@ -53,7 +53,7 @@ class InitiateCallRequest(BaseModel):
     workflow_run_id: int | None = None
     phone_number: str | None = None
     # Optional explicit telephony config to use for the test call. If omitted,
-    # falls back to the user's per-user default (when set), then the org default.
+    # falls back to the org default.
     telephony_configuration_id: int | None = None
     # Optional caller-ID phone number to dial out from. Must belong to the
     # resolved telephony configuration; otherwise the provider picks one.
@@ -82,7 +82,12 @@ async def initiate_call(
     """Initiate a call using the configured telephony provider from web browser. This is
     supposed to be a test call method for the draft version of the agent."""
 
-    user_configuration = await db_client.get_user_configurations(user.id)
+    from api.services.organization_preferences import get_organization_preferences
+
+    preferences = await get_organization_preferences(
+        user.selected_organization_id,
+        db=db_client,
+    )
 
     # Resolve which telephony config to use: explicit request value, otherwise
     # the org's default outbound config.
@@ -116,13 +121,12 @@ async def initiate_call(
             detail="telephony_not_configured",
         )
 
-    phone_number = request.phone_number or user_configuration.test_phone_number
+    phone_number = request.phone_number or preferences.test_phone_number
 
     if not phone_number:
         raise HTTPException(
             status_code=400,
-            detail="Phone number must be provided in request or set in user "
-            "configuration",
+            detail="Phone number must be provided in request or set in organization preferences",
         )
 
     workflow = await db_client.get_workflow(
@@ -132,14 +136,6 @@ async def initiate_call(
         raise HTTPException(status_code=404, detail="Workflow not found")
     execution_user_id = _get_execution_user_id(workflow)
 
-    # Check Dograh quota before initiating the call (apply per-workflow
-    # model_overrides so the keys we will actually use are the ones checked).
-    quota_result = await check_dograh_quota_by_user_id(
-        execution_user_id, workflow_id=workflow.id
-    )
-    if not quota_result.has_quota:
-        raise HTTPException(status_code=402, detail=quota_result.error_message)
-
     # Determine the workflow run mode based on provider type
     workflow_run_mode = provider.PROVIDER_NAME
 
@@ -182,6 +178,16 @@ async def initiate_call(
             )
         workflow_run_name = workflow_run.name
 
+    # Check Dograh quota after the run exists so hosted v2 can mint and store
+    # the MPS correlation id before initiating the call.
+    quota_result = await authorize_workflow_run_start(
+        workflow_id=workflow.id,
+        workflow_run_id=workflow_run_id,
+        actor_user=user,
+    )
+    if not quota_result.has_quota:
+        raise HTTPException(status_code=402, detail=quota_result.error_message)
+
     # Construct webhook URL based on provider type
     backend_endpoint, _ = await get_backend_endpoints()
 
@@ -735,19 +741,8 @@ async def handle_inbound_run(request: Request):
                 TelephonyError.SIGNATURE_VALIDATION_FAILED
             )
 
-        # 4. Quota check (use the workflow's model_overrides if set).
-        quota_result = await check_dograh_quota_by_user_id(
-            user_id, workflow_id=workflow_id
-        )
-        if not quota_result.has_quota:
-            logger.warning(
-                f"User {user_id} has exceeded quota: {quota_result.error_message}"
-            )
-            return provider_class.generate_validation_error_response(
-                TelephonyError.QUOTA_EXCEEDED
-            )
-
-        # 5. Create workflow run + return provider-shaped response.
+        # 5. Create workflow run + authorize quota before returning provider
+        # stream instructions.
         workflow_run_id = await _create_inbound_workflow_run(
             workflow_id,
             user_id,
@@ -756,6 +751,17 @@ async def handle_inbound_run(request: Request):
             telephony_configuration_id=telephony_configuration_id,
             from_phone_number_id=phone_row.id,
         )
+        quota_result = await authorize_workflow_run_start(
+            workflow_id=workflow_id,
+            workflow_run_id=workflow_run_id,
+        )
+        if not quota_result.has_quota:
+            logger.warning(
+                f"User {user_id} has exceeded quota: {quota_result.error_message}"
+            )
+            return provider_class.generate_validation_error_response(
+                TelephonyError.QUOTA_EXCEEDED
+            )
 
         backend_endpoint, wss_backend_endpoint = await get_backend_endpoints()
         websocket_url = (
@@ -870,20 +876,8 @@ async def handle_inbound_telephony(
             logger.error(f"Request validation failed: {error_type}")
             return provider_class.generate_validation_error_response(error_type)
 
-        # Check quota before processing (apply per-workflow model_overrides).
+        # Create workflow run.
         user_id = workflow_context["user_id"]
-        quota_result = await check_dograh_quota_by_user_id(
-            user_id, workflow_id=workflow_id
-        )
-        if not quota_result.has_quota:
-            logger.warning(
-                f"User {user_id} has exceeded quota for inbound calls: {quota_result.error_message}"
-            )
-            return provider_class.generate_validation_error_response(
-                TelephonyError.QUOTA_EXCEEDED
-            )
-
-        # Create workflow run
         workflow_run_id = await _create_inbound_workflow_run(
             workflow_id,
             workflow_context["user_id"],
@@ -892,6 +886,17 @@ async def handle_inbound_telephony(
             telephony_configuration_id=workflow_context["telephony_configuration_id"],
             from_phone_number_id=workflow_context.get("from_phone_number_id"),
         )
+        quota_result = await authorize_workflow_run_start(
+            workflow_id=workflow_id,
+            workflow_run_id=workflow_run_id,
+        )
+        if not quota_result.has_quota:
+            logger.warning(
+                f"User {user_id} has exceeded quota for inbound calls: {quota_result.error_message}"
+            )
+            return provider_class.generate_validation_error_response(
+                TelephonyError.QUOTA_EXCEEDED
+            )
 
         # Generate response URLs
         backend_endpoint, wss_backend_endpoint = await get_backend_endpoints()

api/routes/user.py

@@ -9,7 +9,11 @@ from api.db import db_client
 from api.db.models import (
     UserModel,
 )
+from api.schemas.onboarding_state import OnboardingState, OnboardingStateUpdate
 from api.services.auth.depends import get_user
+from api.services.configuration.ai_model_configuration import (
+    get_resolved_ai_model_configuration,
+)
 from api.services.configuration.check_validity import (
     APIKeyStatusResponse,
     UserConfigurationValidator,
@@ -19,6 +23,14 @@ from api.services.configuration.masking import check_for_masked_keys, mask_user_
 from api.services.configuration.merge import merge_user_configurations
 from api.services.configuration.registry import REGISTRY, ServiceType
 from api.services.mps_service_key_client import mps_service_key_client
+from api.services.organization_preferences import (
+    get_organization_preferences,
+    upsert_organization_preferences,
+)
+from api.services.user_onboarding import (
+    get_onboarding_state,
+    update_onboarding_state,
+)
 
 router = APIRouter(prefix="/user")
 
@@ -91,8 +103,17 @@ class UserConfigurationRequestResponseSchema(BaseModel):
 async def get_user_configurations(
     user: UserModel = Depends(get_user),
 ) -> UserConfigurationRequestResponseSchema:
-    user_configurations = await db_client.get_user_configurations(user.id)
-    masked_config = mask_user_config(user_configurations)
+    resolved_config = await get_resolved_ai_model_configuration(
+        user_id=user.id,
+        organization_id=user.selected_organization_id,
+    )
+    masked_config = mask_user_config(resolved_config.effective)
+    if user.selected_organization_id:
+        preferences = await get_organization_preferences(user.selected_organization_id)
+        if preferences.test_phone_number is not None:
+            masked_config["test_phone_number"] = preferences.test_phone_number
+        if preferences.timezone is not None:
+            masked_config["timezone"] = preferences.timezone
 
     # Add organization pricing info if available
     if user.selected_organization_id:
@@ -118,34 +139,61 @@ async def update_user_configurations(
 
     # Remove organization_pricing from incoming dict as it's read-only
     incoming_dict.pop("organization_pricing", None)
+    preferences_update = {
+        key: incoming_dict.pop(key)
+        for key in ("test_phone_number", "timezone")
+        if key in incoming_dict
+    }
 
-    # Merge via helper
-    try:
-        user_configurations = merge_user_configurations(existing_config, incoming_dict)
-    except ValidationError as e:
-        raise HTTPException(status_code=422, detail=str(e))
+    if incoming_dict:
+        # Merge via helper
+        try:
+            user_configurations = merge_user_configurations(
+                existing_config, incoming_dict
+            )
+        except ValidationError as e:
+            raise HTTPException(status_code=422, detail=str(e))
 
-    try:
-        check_for_masked_keys(user_configurations)
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        try:
+            check_for_masked_keys(user_configurations)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
 
-    try:
-        validator = UserConfigurationValidator()
-        await validator.validate(
-            user_configurations,
-            organization_id=user.selected_organization_id,
-            created_by=user.provider_id,
+        try:
+            validator = UserConfigurationValidator()
+            await validator.validate(
+                user_configurations,
+                organization_id=user.selected_organization_id,
+                created_by=user.provider_id,
+            )
+        except ValueError as e:
+            raise HTTPException(status_code=422, detail=e.args[0])
+
+        user_configurations = await db_client.update_user_configuration(
+            user.id, user_configurations
         )
-    except ValueError as e:
-        raise HTTPException(status_code=422, detail=e.args[0])
+    else:
+        user_configurations = existing_config
 
-    user_configurations = await db_client.update_user_configuration(
-        user.id, user_configurations
-    )
+    if user.selected_organization_id and preferences_update:
+        preferences = await get_organization_preferences(user.selected_organization_id)
+        if "test_phone_number" in preferences_update:
+            preferences.test_phone_number = preferences_update["test_phone_number"]
+        if "timezone" in preferences_update:
+            preferences.timezone = preferences_update["timezone"]
+        await upsert_organization_preferences(
+            user.selected_organization_id,
+            preferences,
+        )
 
     # Return masked version of updated config
     masked_config = mask_user_config(user_configurations)
+    if user.selected_organization_id:
+        preferences = await get_organization_preferences(user.selected_organization_id)
+        if preferences.test_phone_number is not None:
+            masked_config["test_phone_number"] = preferences.test_phone_number
+        if preferences.timezone is not None:
+            masked_config["timezone"] = preferences.timezone
 
     # Add organization pricing info if available
     if user.selected_organization_id:
@@ -160,12 +208,31 @@ async def update_user_configurations(
     return masked_config
 
 
+@router.get("/onboarding-state")
+async def get_user_onboarding_state(
+    user: UserModel = Depends(get_user),
+) -> OnboardingState:
+    return await get_onboarding_state(user.id)
+
+
+@router.put("/onboarding-state")
+async def update_user_onboarding_state(
+    request: OnboardingStateUpdate,
+    user: UserModel = Depends(get_user),
+) -> OnboardingState:
+    return await update_onboarding_state(user.id, request)
+
+
 @router.get("/configurations/user/validate")
 async def validate_user_configurations(
     validity_ttl_seconds: int = Query(default=60, ge=0, le=86400),
     user: UserModel = Depends(get_user),
 ) -> APIKeyStatusResponse:
-    configurations = await db_client.get_user_configurations(user.id)
+    resolved_config = await get_resolved_ai_model_configuration(
+        user_id=user.id,
+        organization_id=user.selected_organization_id,
+    )
+    configurations = resolved_config.effective
 
     if (
         configurations.last_validated_at

api/routes/webrtc_signaling.py

@@ -19,7 +19,7 @@ import ipaddress
 import os
 from datetime import UTC, datetime
 from enum import Enum
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Set
 
 from aiortc import RTCIceServer
 from aiortc.sdp import candidate_from_sdp
@@ -45,7 +45,7 @@ from api.services.pipecat.ws_sender_registry import (
     register_ws_sender,
     unregister_ws_sender,
 )
-from api.services.quota_service import check_dograh_quota
+from api.services.quota_service import authorize_workflow_run_start
 
 router = APIRouter(prefix="/ws")
 
@@ -246,6 +246,74 @@ class SignalingManager:
     def __init__(self):
         self._connections: Dict[str, WebSocket] = {}
         self._peer_connections: Dict[str, SmallWebRTCConnection] = {}
+        self._connection_peer_ids: Dict[str, Set[str]] = {}
+        self._peer_connection_owners: Dict[str, str] = {}
+
+    def _track_peer_connection(
+        self, connection_id: str, pc_id: str, pc: SmallWebRTCConnection
+    ) -> None:
+        self._peer_connections[pc_id] = pc
+        self._peer_connection_owners[pc_id] = connection_id
+        self._connection_peer_ids.setdefault(connection_id, set()).add(pc_id)
+
+    def _forget_peer_connection(self, pc_id: str) -> Optional[str]:
+        connection_id = self._peer_connection_owners.pop(pc_id, None)
+        self._peer_connections.pop(pc_id, None)
+
+        if connection_id:
+            peer_ids = self._connection_peer_ids.get(connection_id)
+            if peer_ids is not None:
+                peer_ids.discard(pc_id)
+                if not peer_ids:
+                    self._connection_peer_ids.pop(connection_id, None)
+
+        return connection_id
+
+    async def _send_json_if_connected(
+        self, websocket: WebSocket, message: dict
+    ) -> bool:
+        if websocket.application_state != WebSocketState.CONNECTED:
+            return False
+
+        try:
+            await websocket.send_json(message)
+            return True
+        except Exception as e:
+            logger.debug(f"Failed to send signaling WebSocket message: {e}")
+            return False
+
+    async def _close_websocket_if_connected(
+        self, websocket: WebSocket, code: int = 1000, reason: str = ""
+    ) -> None:
+        if websocket.application_state != WebSocketState.CONNECTED:
+            return
+
+        try:
+            await websocket.close(code=code, reason=reason)
+        except Exception as e:
+            logger.debug(f"Failed to close signaling WebSocket: {e}")
+
+    async def _notify_call_ended_and_close_websocket(
+        self,
+        websocket: WebSocket,
+        workflow_run_id: int,
+        pc_id: str,
+        reason: str,
+    ) -> None:
+        await self._send_json_if_connected(
+            websocket,
+            {
+                "type": "call-ended",
+                "payload": {
+                    "workflow_run_id": workflow_run_id,
+                    "pc_id": pc_id,
+                    "reason": reason,
+                },
+            },
+        )
+        await self._close_websocket_if_connected(
+            websocket, code=1000, reason="call ended"
+        )
 
     async def handle_websocket(
         self,
@@ -257,35 +325,51 @@ class SignalingManager:
         """Handle WebSocket connection for signaling."""
         await websocket.accept()
         connection_id = f"{workflow_id}:{workflow_run_id}:{user.id}"
-        self._connections[connection_id] = websocket
+        connection_key = f"{connection_id}:{id(websocket)}"
+        self._connections[connection_key] = websocket
 
         try:
             while True:
                 message = await websocket.receive_json()
                 await self._handle_message(
-                    websocket, message, workflow_id, workflow_run_id, user
+                    websocket,
+                    message,
+                    workflow_id,
+                    workflow_run_id,
+                    user,
+                    connection_key,
                 )
         except WebSocketDisconnect:
             logger.info(f"WebSocket disconnected for {connection_id}")
         except Exception as e:
-            logger.error(f"WebSocket error for {connection_id}: {e}")
+            if websocket.application_state == WebSocketState.DISCONNECTED:
+                logger.info(f"WebSocket disconnected for {connection_id}")
+            else:
+                logger.error(f"WebSocket error for {connection_id}: {e}")
         finally:
             # Cleanup
-            self._connections.pop(connection_id, None)
+            self._connections.pop(connection_key, None)
+            peer_ids = list(self._connection_peer_ids.pop(connection_key, set()))
 
             # Unregister WebSocket sender for real-time feedback
             unregister_ws_sender(workflow_run_id)
 
-            # Clean up all peer connections for this workflow run
+            # Clean up peer connections owned by this WebSocket.
             # Note: In a WebSocket-based signaling approach (vs HTTP PATCH),
             # we maintain our own connection map instead of relying on
             # SmallWebRTCRequestHandler's _pcs_map. This is suitable for
             # multi-worker FastAPI deployments where state cannot be shared.
-            for pc_id in list(self._peer_connections.keys()):
+            for pc_id in peer_ids:
+                self._peer_connection_owners.pop(pc_id, None)
                 pc = self._peer_connections.pop(pc_id, None)
                 if pc:
-                    await pc.disconnect()
-                    logger.debug(f"Disconnected peer connection: {pc_id}")
+                    try:
+                        await pc.disconnect()
+                        logger.debug(f"Disconnected peer connection: {pc_id}")
+                    except Exception as e:
+                        logger.debug(
+                            f"Failed to disconnect peer connection {pc_id}: {e}"
+                        )
 
     async def _handle_message(
         self,
@@ -294,17 +378,20 @@ class SignalingManager:
         workflow_id: int,
         workflow_run_id: int,
         user: UserModel,
+        connection_key: str,
     ):
         """Handle incoming WebSocket messages."""
         msg_type = message.get("type")
         payload = message.get("payload", {})
 
         if msg_type == "offer":
-            await self._handle_offer(ws, payload, workflow_id, workflow_run_id, user)
+            await self._handle_offer(
+                ws, payload, workflow_id, workflow_run_id, user, connection_key
+            )
         elif msg_type == "ice-candidate":
-            await self._handle_ice_candidate(ws, payload, workflow_run_id)
+            await self._handle_ice_candidate(payload, connection_key)
         elif msg_type == "renegotiate":
-            await self._handle_renegotiation(ws, payload, workflow_id, workflow_run_id)
+            await self._handle_renegotiation(ws, payload, connection_key)
 
     async def _handle_offer(
         self,
@@ -313,6 +400,7 @@ class SignalingManager:
         workflow_id: int,
         workflow_run_id: int,
         user: UserModel,
+        connection_key: str,
     ):
         """Handle offer message and create answer with ICE trickling."""
         pc_id = payload.get("pc_id")
@@ -320,6 +408,15 @@ class SignalingManager:
         type_ = payload.get("type")
         call_context_vars = payload.get("call_context_vars", {})
 
+        if not pc_id or not sdp or not type_:
+            await ws.send_json(
+                {
+                    "type": "error",
+                    "payload": {"message": "Missing offer fields"},
+                }
+            )
+            return
+
         # Set run context for logging and tracing. org_id must be set before
         # pc.initialize() so that aiortc's internal tasks inherit it.
         set_current_run_id(workflow_run_id)
@@ -329,7 +426,11 @@ class SignalingManager:
 
         # Check Dograh quota before initiating the call (apply per-workflow
         # model_overrides so we evaluate the keys this workflow will use).
-        quota_result = await check_dograh_quota(user, workflow_id=workflow_id)
+        quota_result = await authorize_workflow_run_start(
+            workflow_id=workflow_id,
+            workflow_run_id=workflow_run_id,
+            actor_user=user,
+        )
         if not quota_result.has_quota:
             # Send error response for quota issues
             await ws.send_json(
@@ -343,7 +444,16 @@ class SignalingManager:
             )
             return
 
-        if pc_id and pc_id in self._peer_connections:
+        if pc_id in self._peer_connections:
+            if self._peer_connection_owners.get(pc_id) != connection_key:
+                await ws.send_json(
+                    {
+                        "type": "error",
+                        "payload": {"message": "Peer connection already owned"},
+                    }
+                )
+                return
+
             # Reuse existing connection
             logger.info(f"Reusing existing connection for pc_id: {pc_id}")
             pc = self._peer_connections[pc_id]
@@ -375,7 +485,7 @@ class SignalingManager:
             await pc.initialize(sdp=sdp, type=type_)
 
             # Store peer connection using client's pc_id
-            self._peer_connections[pc_id] = pc
+            self._track_peer_connection(connection_key, pc_id, pc)
 
             # Register WebSocket sender for real-time feedback
             async def ws_sender(message: dict):
@@ -388,7 +498,16 @@ class SignalingManager:
             @pc.event_handler("closed")
             async def handle_disconnected(webrtc_connection: SmallWebRTCConnection):
                 logger.info(f"PeerConnection closed: {webrtc_connection.pc_id}")
-                self._peer_connections.pop(webrtc_connection.pc_id, None)
+                owner_connection_id = self._forget_peer_connection(
+                    webrtc_connection.pc_id
+                )
+                if owner_connection_id == connection_key:
+                    await self._notify_call_ended_and_close_websocket(
+                        ws,
+                        workflow_run_id,
+                        webrtc_connection.pc_id,
+                        reason="peer_connection_closed",
+                    )
 
             # Start pipeline in background
             asyncio.create_task(
@@ -417,9 +536,7 @@ class SignalingManager:
                 }
             )
 
-    async def _handle_ice_candidate(
-        self, ws: WebSocket, payload: dict, workflow_run_id: int
-    ):
+    async def _handle_ice_candidate(self, payload: dict, connection_key: str):
         """Handle incoming ICE candidate from client.
 
         Uses SmallWebRTC's native ICE trickling support via add_ice_candidate().
@@ -438,6 +555,9 @@ class SignalingManager:
         if not pc:
             logger.warning(f"No peer connection found for pc_id: {pc_id}")
             return
+        if self._peer_connection_owners.get(pc_id) != connection_key:
+            logger.warning(f"Ignoring ICE candidate for unowned pc_id: {pc_id}")
+            return
 
         if candidate_data:
             candidate_str = candidate_data.get("candidate", "")
@@ -462,7 +582,7 @@ class SignalingManager:
             logger.debug(f"End of ICE candidates for pc_id: {pc_id}")
 
     async def _handle_renegotiation(
-        self, ws: WebSocket, payload: dict, workflow_id: int, workflow_run_id: int
+        self, ws: WebSocket, payload: dict, connection_key: str
     ):
         """Handle renegotiation request."""
         pc_id = payload.get("pc_id")
@@ -475,6 +595,11 @@ class SignalingManager:
                 {"type": "error", "payload": {"message": "Peer connection not found"}}
             )
             return
+        if self._peer_connection_owners.get(pc_id) != connection_key:
+            await ws.send_json(
+                {"type": "error", "payload": {"message": "Peer connection not found"}}
+            )
+            return
 
         pc = self._peer_connections[pc_id]
         await pc.renegotiate(sdp=sdp, type=type_, restart_pc=restart_pc)

api/routes/workflow.py

@@ -15,10 +15,19 @@ from api.db import db_client
 from api.db.agent_trigger_client import TriggerPathConflictError
 from api.db.models import UserModel
 from api.db.workflow_template_client import WorkflowTemplateClient
-from api.enums import CallType, PostHogEvent, StorageBackend
+from api.enums import CallType, PostHogEvent, StorageBackend, WorkflowStatus
+from api.schemas.ai_model_configuration import OrganizationAIModelConfigurationV2
 from api.schemas.workflow import WorkflowRunResponseSchema
 from api.sdk_expose import sdk_expose
 from api.services.auth.depends import get_user
+from api.services.configuration.ai_model_configuration import (
+    WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY,
+    check_for_masked_keys_in_ai_model_configuration_v2,
+    compile_ai_model_configuration_v2,
+    convert_legacy_ai_model_configuration_to_v2,
+    get_resolved_ai_model_configuration,
+    merge_ai_model_configuration_v2_secrets,
+)
 from api.services.configuration.check_validity import UserConfigurationValidator
 from api.services.configuration.masking import (
     mask_workflow_configurations,
@@ -32,12 +41,15 @@ from api.services.configuration.resolve import (
 )
 from api.services.mps_service_key_client import mps_service_key_client
 from api.services.posthog_client import capture_event
-from api.services.pricing.run_usage_response import format_public_usage_info
 from api.services.reports import generate_workflow_report_csv
 from api.services.storage import storage_fs
 from api.services.workflow.dto import ReactFlowDTO, sanitize_workflow_definition
 from api.services.workflow.duplicate import duplicate_workflow
 from api.services.workflow.errors import ItemKind, WorkflowError
+from api.services.workflow.run_usage_response import (
+    format_public_cost_info,
+    format_public_usage_info,
+)
 from api.services.workflow.trigger_paths import (
     TriggerPathIssue,
     ensure_trigger_paths,
@@ -48,6 +60,10 @@ from api.services.workflow.trigger_paths import (
 )
 from api.services.workflow.workflow_graph import WorkflowGraph
 from api.utils.artifacts import artifact_url
+from api.utils.recording_artifacts import (
+    get_recording_storage_key,
+    has_recording_track,
+)
 
 router = APIRouter(prefix="/workflow")
 
@@ -562,6 +578,31 @@ async def get_workflow_count(
     )
 
 
+def _validate_status_filter(status: Optional[str]) -> List[str]:
+    """Parse and validate a workflow ``status`` query filter.
+
+    Accepts a single value or a comma-separated list. Returns the list of
+    validated status values (empty when no filter was supplied). Any value
+    outside the ``workflow_status`` enum raises 422 so the request fails as a
+    clean client error instead of a 500 from the Postgres enum cast.
+    """
+    if status is None or status == "":
+        return []
+    allowed = {s.value for s in WorkflowStatus}
+    requested = [s.strip() for s in status.split(",")]
+    invalid = sorted({s for s in requested if s not in allowed})
+    if invalid:
+        invalid_display = ["<empty>" if s == "" else s for s in invalid]
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                f"Invalid workflow status filter: {invalid_display}. "
+                f"Allowed values: {sorted(allowed)}."
+            ),
+        )
+    return requested
+
+
 @router.get(
     "/fetch",
     **sdk_expose(
@@ -581,21 +622,22 @@ async def get_workflows(
     Returns a lightweight response with only essential fields for listing.
     Use GET /workflow/fetch/{workflow_id} to get full workflow details.
     """
-    # Handle comma-separated status values
-    if status and "," in status:
-        # Split comma-separated values and fetch workflows for each status
-        status_list = [s.strip() for s in status.split(",")]
+    statuses = _validate_status_filter(status)
+    if statuses:
+        # Fetch workflows for each requested status and combine the results.
         all_workflows = []
-        for status_value in status_list:
-            workflows = await db_client.get_all_workflows_for_listing(
-                organization_id=user.selected_organization_id, status=status_value
+        for status_value in statuses:
+            all_workflows.extend(
+                await db_client.get_all_workflows_for_listing(
+                    organization_id=user.selected_organization_id,
+                    status=status_value,
+                )
             )
-            all_workflows.extend(workflows)
         workflows = all_workflows
     else:
-        # Single status or no status filter
+        # No status filter
         workflows = await db_client.get_all_workflows_for_listing(
-            organization_id=user.selected_organization_id, status=status
+            organization_id=user.selected_organization_id, status=None
         )
 
     # Get run counts for all workflows in a single query
@@ -804,10 +846,20 @@ async def get_workflows_summary(
     ),
 ) -> List[WorkflowSummaryResponse]:
     """Get minimal workflow information (id and name only) for all workflows"""
-    workflows = await db_client.get_all_workflows(
-        organization_id=user.selected_organization_id,
-        status=status,
-    )
+    statuses = _validate_status_filter(status)
+    if statuses:
+        workflows = []
+        for status_value in statuses:
+            workflows.extend(
+                await db_client.get_all_workflows(
+                    organization_id=user.selected_organization_id,
+                    status=status_value,
+                )
+            )
+    else:
+        workflows = await db_client.get_all_workflows(
+            organization_id=user.selected_organization_id, status=None
+        )
     return [
         WorkflowSummaryResponse(id=workflow.id, name=workflow.name)
         for workflow in workflows
@@ -955,12 +1007,74 @@ async def update_workflow(
                     existing_def,
                 )
 
-        # Validate model_overrides: resolve onto global config, then
-        # run the same validator used by the user-configurations endpoint.
-        # Also stamp the current global API key into the override so the override
-        # remains functional if the global config later switches to a different provider.
+        # Validate model overrides. v2 uses a complete workflow-level model
+        # configuration; legacy v1 uses partial service overlays.
         workflow_configurations = request.workflow_configurations
-        if workflow_configurations and workflow_configurations.get("model_overrides"):
+        if workflow_configurations and workflow_configurations.get(
+            WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY
+        ):
+            existing_workflow = await db_client.get_workflow(
+                workflow_id, organization_id=user.selected_organization_id
+            )
+            if existing_workflow is None:
+                raise HTTPException(
+                    status_code=404, detail=f"Workflow with id {workflow_id} not found"
+                )
+            existing_draft = await db_client.get_draft_version(workflow_id)
+            existing_configs = (
+                existing_draft.workflow_configurations
+                if existing_draft
+                else existing_workflow.released_definition.workflow_configurations
+            )
+            existing_v2_override = (existing_configs or {}).get(
+                WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY
+            )
+            try:
+                incoming_v2_override = (
+                    OrganizationAIModelConfigurationV2.model_validate(
+                        workflow_configurations[
+                            WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY
+                        ]
+                    )
+                )
+                existing_v2_override_config = (
+                    OrganizationAIModelConfigurationV2.model_validate(
+                        existing_v2_override
+                    )
+                    if existing_v2_override
+                    else None
+                )
+                v2_override = merge_ai_model_configuration_v2_secrets(
+                    incoming_v2_override,
+                    existing_v2_override_config,
+                )
+                if existing_v2_override_config is None:
+                    resolved_config = await get_resolved_ai_model_configuration(
+                        user_id=user.id,
+                        organization_id=user.selected_organization_id,
+                    )
+                    v2_override = merge_ai_model_configuration_v2_secrets(
+                        v2_override,
+                        resolved_config.organization_configuration,
+                    )
+                check_for_masked_keys_in_ai_model_configuration_v2(v2_override)
+                effective = compile_ai_model_configuration_v2(v2_override)
+                await UserConfigurationValidator().validate(
+                    effective,
+                    organization_id=user.selected_organization_id,
+                    created_by=user.provider_id,
+                )
+            except (ValidationError, ValueError) as e:
+                raise HTTPException(status_code=422, detail=str(e))
+            workflow_configurations = {
+                **workflow_configurations,
+                WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY: v2_override.model_dump(
+                    mode="json",
+                    exclude_none=True,
+                ),
+            }
+            workflow_configurations.pop("model_overrides", None)
+        elif workflow_configurations and workflow_configurations.get("model_overrides"):
             existing_workflow = await db_client.get_workflow(
                 workflow_id, organization_id=user.selected_organization_id
             )
@@ -978,24 +1092,48 @@ async def update_workflow(
                 workflow_configurations,
                 existing_configs,
             )
-            user_config = await db_client.get_user_configurations(user.id)
+            resolved_config = await get_resolved_ai_model_configuration(
+                user_id=user.id,
+                organization_id=user.selected_organization_id,
+            )
+            effective_config = resolved_config.effective
             try:
                 enriched_overrides = enrich_overrides_with_api_keys(
                     workflow_configurations["model_overrides"],
-                    user_config,
+                    effective_config,
                 )
-                effective = resolve_effective_config(user_config, enriched_overrides)
-                await UserConfigurationValidator().validate(
-                    effective,
-                    organization_id=user.selected_organization_id,
-                    created_by=user.provider_id,
+                effective = resolve_effective_config(
+                    effective_config, enriched_overrides
                 )
+                if resolved_config.source == "organization_v2":
+                    v2_override = convert_legacy_ai_model_configuration_to_v2(effective)
+                    await UserConfigurationValidator().validate(
+                        compile_ai_model_configuration_v2(v2_override),
+                        organization_id=user.selected_organization_id,
+                        created_by=user.provider_id,
+                    )
+                else:
+                    await UserConfigurationValidator().validate(
+                        effective,
+                        organization_id=user.selected_organization_id,
+                        created_by=user.provider_id,
+                    )
             except ValueError as e:
                 raise HTTPException(status_code=422, detail=str(e))
-            workflow_configurations = {
-                **workflow_configurations,
-                "model_overrides": enriched_overrides,
-            }
+            if resolved_config.source == "organization_v2":
+                workflow_configurations = {
+                    **workflow_configurations,
+                    WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY: v2_override.model_dump(
+                        mode="json",
+                        exclude_none=True,
+                    ),
+                }
+                workflow_configurations.pop("model_overrides", None)
+            else:
+                workflow_configurations = {
+                    **workflow_configurations,
+                    "model_overrides": enriched_overrides,
+                }
 
         # Reject upfront if any new trigger path collides with another
         # workflow's trigger — keeps the workflow record from
@@ -1157,7 +1295,16 @@ async def get_workflow_run(
         raise HTTPException(status_code=404, detail="Workflow run not found")
 
     public_access_token = run.public_access_token
-    if (run.transcript_url or run.recording_url) and not public_access_token:
+    user_recording_url = get_recording_storage_key(run.extra, "user")
+    bot_recording_url = get_recording_storage_key(run.extra, "bot")
+    has_user_recording = has_recording_track(run.extra, "user")
+    has_bot_recording = has_recording_track(run.extra, "bot")
+    if (
+        run.transcript_url
+        or run.recording_url
+        or has_user_recording
+        or has_bot_recording
+    ) and not public_access_token:
         public_access_token = await db_client.ensure_public_access_token(run.id)
 
     return {
@@ -1168,25 +1315,22 @@ async def get_workflow_run(
         "is_completed": run.is_completed,
         "transcript_url": run.transcript_url,
         "recording_url": run.recording_url,
+        "user_recording_url": user_recording_url,
+        "bot_recording_url": bot_recording_url,
         "transcript_public_url": artifact_url(public_access_token, "transcript"),
         "recording_public_url": artifact_url(public_access_token, "recording"),
+        "user_recording_public_url": (
+            artifact_url(public_access_token, "user_recording")
+            if has_user_recording
+            else None
+        ),
+        "bot_recording_public_url": (
+            artifact_url(public_access_token, "bot_recording")
+            if has_bot_recording
+            else None
+        ),
         "public_access_token": public_access_token,
-        "cost_info": {
-            "dograh_token_usage": (
-                run.cost_info.get("dograh_token_usage")
-                if run.cost_info and "dograh_token_usage" in run.cost_info
-                else round(float(run.cost_info.get("total_cost_usd", 0)) * 100, 2)
-                if run.cost_info and "total_cost_usd" in run.cost_info
-                else 0
-            ),
-            "call_duration_seconds": int(
-                round(run.cost_info.get("call_duration_seconds"))
-            )
-            if run.cost_info and run.cost_info.get("call_duration_seconds") is not None
-            else None,
-        }
-        if run.cost_info
-        else None,
+        "cost_info": format_public_cost_info(run.cost_info, run.usage_info),
         "usage_info": format_public_usage_info(run.usage_info),
         "created_at": run.created_at,
         "definition_id": run.definition_id,

api/routes/workflow_text_chat.py

@@ -9,8 +9,8 @@ from pydantic import BaseModel, Field
 from api.db import db_client
 from api.db.models import UserModel, WorkflowRunTextSessionModel
 from api.enums import WorkflowRunMode
-from api.services.auth.depends import get_user
-from api.services.quota_service import check_dograh_quota
+from api.services.auth.depends import get_user_with_selected_organization
+from api.services.quota_service import authorize_workflow_run_start
 from api.services.workflow.text_chat_session_service import (
     TextChatPendingTurnLostError,
     TextChatSessionExecutionError,
@@ -96,14 +96,16 @@ def _revision_conflict_detail(e: Any) -> dict[str, Any]:
     }
 
 
-def _require_selected_organization_id(user: UserModel) -> int:
-    if user.selected_organization_id is None:
-        raise HTTPException(status_code=403, detail="Organization context is required")
-    return user.selected_organization_id
-
-
-async def _ensure_text_chat_quota(user: UserModel, workflow_id: int) -> None:
-    quota_result = await check_dograh_quota(user, workflow_id=workflow_id)
+async def _ensure_text_chat_quota(
+    user: UserModel,
+    workflow_id: int,
+    workflow_run_id: int,
+) -> None:
+    quota_result = await authorize_workflow_run_start(
+        workflow_id=workflow_id,
+        workflow_run_id=workflow_run_id,
+        actor_user=user,
+    )
     if not quota_result.has_quota:
         raise HTTPException(status_code=402, detail=quota_result.error_message)
 
@@ -114,9 +116,8 @@ async def _load_text_session_or_404(
     user: UserModel,
 ) -> WorkflowRunTextSessionModel:
     set_current_run_id(run_id)
-    organization_id = _require_selected_organization_id(user)
     text_session = await db_client.get_workflow_run_text_session(
-        run_id, organization_id=organization_id
+        run_id, organization_id=user.selected_organization_id
     )
     if not text_session or not text_session.workflow_run:
         raise HTTPException(status_code=404, detail="Text chat session not found")
@@ -158,11 +159,8 @@ async def _execute_pending_turn_response(
 async def create_text_chat_session(
     workflow_id: int,
     request: CreateTextChatSessionRequest,
-    user: UserModel = Depends(get_user),
+    user: UserModel = Depends(get_user_with_selected_organization),
 ) -> WorkflowRunTextSessionResponse:
-    organization_id = _require_selected_organization_id(user)
-    await _ensure_text_chat_quota(user, workflow_id)
-
     session_name = request.name or f"WR-TEXT-{uuid4().hex[:6].upper()}"
     try:
         workflow_run = await db_client.create_workflow_run(
@@ -172,12 +170,13 @@ async def create_text_chat_session(
             user_id=user.id,
             initial_context=request.initial_context,
             use_draft=True,
-            organization_id=organization_id,
+            organization_id=user.selected_organization_id,
         )
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e))
 
     set_current_run_id(workflow_run.id)
+    await _ensure_text_chat_quota(user, workflow_id, workflow_run.id)
 
     annotations = {
         "tester": {
@@ -220,7 +219,7 @@ async def create_text_chat_session(
 async def get_text_chat_session(
     workflow_id: int,
     run_id: int,
-    user: UserModel = Depends(get_user),
+    user: UserModel = Depends(get_user_with_selected_organization),
 ) -> WorkflowRunTextSessionResponse:
     text_session = await _load_text_session_or_404(workflow_id, run_id, user)
     return _build_response(text_session)
@@ -234,10 +233,10 @@ async def append_text_chat_message(
     workflow_id: int,
     run_id: int,
     request: AppendTextChatMessageRequest,
-    user: UserModel = Depends(get_user),
+    user: UserModel = Depends(get_user_with_selected_organization),
 ) -> WorkflowRunTextSessionResponse:
     text_session = await _load_text_session_or_404(workflow_id, run_id, user)
-    await _ensure_text_chat_quota(user, workflow_id)
+    await _ensure_text_chat_quota(user, workflow_id, run_id)
 
     try:
         text_session = await append_text_chat_user_message(
@@ -264,7 +263,7 @@ async def rewind_text_chat_session(
     workflow_id: int,
     run_id: int,
     request: RewindTextChatSessionRequest,
-    user: UserModel = Depends(get_user),
+    user: UserModel = Depends(get_user_with_selected_organization),
 ) -> WorkflowRunTextSessionResponse:
     text_session = await _load_text_session_or_404(workflow_id, run_id, user)
     try:

api/schemas/ai_model_configuration.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from api.services.configuration.registry import (
+    DograhEmbeddingsConfiguration,
+    DograhLLMService,
+    DograhSTTService,
+    DograhTTSService,
+    EmbeddingsConfig,
+    LLMConfig,
+    RealtimeConfig,
+    ServiceProviders,
+    STTConfig,
+    TTSConfig,
+)
+
+DOGRAH_SPEED_OPTIONS: tuple[float, ...] = (0.8, 1.0, 1.2)
+DOGRAH_DEFAULT_VOICE = "default"
+DOGRAH_DEFAULT_LANGUAGE = "multi"
+
+
+class EffectiveAIModelConfiguration(BaseModel):
+    llm: LLMConfig | None = None
+    stt: STTConfig | None = None
+    tts: TTSConfig | None = None
+    embeddings: EmbeddingsConfig | None = None
+    realtime: RealtimeConfig | None = None
+    is_realtime: bool = False
+    managed_service_version: int | None = None
+    test_phone_number: str | None = None
+    timezone: str | None = None
+    last_validated_at: datetime | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def strip_incomplete_realtime_when_disabled(cls, data):
+        """Skip realtime validation when is_realtime is False and api_key is missing."""
+        if isinstance(data, dict) and not data.get("is_realtime", False):
+            realtime = data.get("realtime")
+            if isinstance(realtime, dict) and not realtime.get("api_key"):
+                data.pop("realtime", None)
+        return data
+
+
+class DograhManagedAIModelConfiguration(BaseModel):
+    api_key: str
+    voice: str = DOGRAH_DEFAULT_VOICE
+    speed: float = Field(default=1.0)
+    language: str = DOGRAH_DEFAULT_LANGUAGE
+
+    @model_validator(mode="after")
+    def validate_speed(self):
+        if self.speed not in DOGRAH_SPEED_OPTIONS:
+            allowed = ", ".join(str(speed) for speed in DOGRAH_SPEED_OPTIONS)
+            raise ValueError(f"Dograh speed must be one of: {allowed}")
+        return self
+
+
+class BYOKPipelineAIModelConfiguration(BaseModel):
+    llm: LLMConfig
+    tts: TTSConfig
+    stt: STTConfig
+    embeddings: EmbeddingsConfig | None = None
+
+    @model_validator(mode="after")
+    def reject_dograh_providers(self):
+        _reject_dograh_provider("llm", self.llm)
+        _reject_dograh_provider("tts", self.tts)
+        _reject_dograh_provider("stt", self.stt)
+        _reject_dograh_provider("embeddings", self.embeddings)
+        return self
+
+
+class BYOKRealtimeAIModelConfiguration(BaseModel):
+    realtime: RealtimeConfig
+    llm: LLMConfig
+    embeddings: EmbeddingsConfig | None = None
+
+    @model_validator(mode="after")
+    def reject_dograh_providers(self):
+        _reject_dograh_provider("llm", self.llm)
+        _reject_dograh_provider("embeddings", self.embeddings)
+        return self
+
+
+class BYOKAIModelConfiguration(BaseModel):
+    mode: Literal["pipeline", "realtime"]
+    pipeline: BYOKPipelineAIModelConfiguration | None = None
+    realtime: BYOKRealtimeAIModelConfiguration | None = None
+
+    @model_validator(mode="after")
+    def validate_selected_mode(self):
+        if self.mode == "pipeline" and self.pipeline is None:
+            raise ValueError("byok.pipeline is required when byok.mode is pipeline")
+        if self.mode == "realtime" and self.realtime is None:
+            raise ValueError("byok.realtime is required when byok.mode is realtime")
+        return self
+
+
+class OrganizationAIModelConfigurationV2(BaseModel):
+    version: Literal[2] = 2
+    mode: Literal["dograh", "byok"]
+    dograh: DograhManagedAIModelConfiguration | None = None
+    byok: BYOKAIModelConfiguration | None = None
+
+    @model_validator(mode="after")
+    def validate_selected_mode(self):
+        if self.mode == "dograh" and self.dograh is None:
+            raise ValueError("dograh configuration is required when mode is dograh")
+        if self.mode == "byok" and self.byok is None:
+            raise ValueError("byok configuration is required when mode is byok")
+        return self
+
+
+class OrganizationAIModelConfigurationResponse(BaseModel):
+    configuration: dict | None
+    effective_configuration: dict
+    source: Literal["organization_v2", "legacy_user_v1", "empty"]
+
+
+def compile_ai_model_configuration_v2(
+    configuration: OrganizationAIModelConfigurationV2,
+) -> EffectiveAIModelConfiguration:
+    if configuration.mode == "dograh":
+        if configuration.dograh is None:
+            raise ValueError("dograh configuration is required")
+        return _compile_dograh_configuration(configuration.dograh)
+
+    if configuration.byok is None:
+        raise ValueError("byok configuration is required")
+    if configuration.byok.mode == "pipeline":
+        if configuration.byok.pipeline is None:
+            raise ValueError("byok.pipeline is required")
+        pipeline = configuration.byok.pipeline
+        return EffectiveAIModelConfiguration(
+            llm=pipeline.llm,
+            tts=pipeline.tts,
+            stt=pipeline.stt,
+            embeddings=pipeline.embeddings,
+            is_realtime=False,
+        )
+
+    if configuration.byok.realtime is None:
+        raise ValueError("byok.realtime is required")
+    realtime = configuration.byok.realtime
+    return EffectiveAIModelConfiguration(
+        llm=realtime.llm,
+        realtime=realtime.realtime,
+        embeddings=realtime.embeddings,
+        is_realtime=True,
+    )
+
+
+def _compile_dograh_configuration(
+    configuration: DograhManagedAIModelConfiguration,
+) -> EffectiveAIModelConfiguration:
+    return EffectiveAIModelConfiguration(
+        llm=DograhLLMService(
+            provider=ServiceProviders.DOGRAH,
+            api_key=configuration.api_key,
+            model="default",
+        ),
+        tts=DograhTTSService(
+            provider=ServiceProviders.DOGRAH,
+            api_key=configuration.api_key,
+            model="default",
+            voice=configuration.voice,
+            speed=configuration.speed,
+        ),
+        stt=DograhSTTService(
+            provider=ServiceProviders.DOGRAH,
+            api_key=configuration.api_key,
+            model="default",
+            language=configuration.language,
+        ),
+        embeddings=DograhEmbeddingsConfiguration(
+            provider=ServiceProviders.DOGRAH,
+            api_key=configuration.api_key,
+            model="default",
+        ),
+        is_realtime=False,
+        managed_service_version=2,
+    )
+
+
+def _reject_dograh_provider(section: str, service) -> None:
+    if service is None:
+        return
+    if getattr(service, "provider", None) == ServiceProviders.DOGRAH:
+        raise ValueError(f"BYOK {section} cannot use Dograh provider")

api/schemas/onboarding_state.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class OnboardingState(BaseModel):
+    """Per-user onboarding state, stored under UserConfigurationKey.ONBOARDING.
+
+    Server-authoritative replacement for the browser-localStorage onboarding
+    store, so the post-signup gate and one-time tooltips hold across devices.
+    """
+
+    # Post-signup onboarding form gate: set once on submit/skip.
+    completed_at: datetime | None = None
+    skipped: bool = False
+    # One-time UI affordances (tooltip keys, milestone action keys). Kept as
+    # free-form strings — the UI owns the vocabulary.
+    seen_tooltips: list[str] = Field(default_factory=list)
+    completed_actions: list[str] = Field(default_factory=list)
+
+
+class OnboardingStateUpdate(BaseModel):
+    """Partial update merged into the stored state.
+
+    Scalars overwrite when supplied; list entries are unioned into the stored
+    lists, so concurrent updates (e.g. two tabs marking different tooltips)
+    don't drop each other's items.
+    """
+
+    completed_at: datetime | None = None
+    skipped: bool | None = None
+    seen_tooltips: list[str] | None = None
+    completed_actions: list[str] | None = None
+
+    def apply_to(self, state: OnboardingState) -> OnboardingState:
+        merged = state.model_copy(deep=True)
+        if self.completed_at is not None:
+            merged.completed_at = self.completed_at
+        if self.skipped is not None:
+            merged.skipped = self.skipped
+        for tooltip in self.seen_tooltips or []:
+            if tooltip not in merged.seen_tooltips:
+                merged.seen_tooltips.append(tooltip)
+        for action in self.completed_actions or []:
+            if action not in merged.completed_actions:
+                merged.completed_actions.append(action)
+        return merged

api/schemas/organization_preferences.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel
+
+
+class OrganizationPreferences(BaseModel):
+    test_phone_number: str | None = None
+    timezone: str | None = None

api/schemas/user_configuration.py

@@ -1,33 +0,0 @@
-from datetime import datetime
-
-from pydantic import BaseModel, model_validator
-
-from api.services.configuration.registry import (
-    EmbeddingsConfig,
-    LLMConfig,
-    RealtimeConfig,
-    STTConfig,
-    TTSConfig,
-)
-
-
-class UserConfiguration(BaseModel):
-    llm: LLMConfig | None = None
-    stt: STTConfig | None = None
-    tts: TTSConfig | None = None
-    embeddings: EmbeddingsConfig | None = None
-    realtime: RealtimeConfig | None = None
-    is_realtime: bool = False
-    test_phone_number: str | None = None
-    timezone: str | None = None
-    last_validated_at: datetime | None = None
-
-    @model_validator(mode="before")
-    @classmethod
-    def strip_incomplete_realtime_when_disabled(cls, data):
-        """Skip realtime validation when is_realtime is False and api_key is missing."""
-        if isinstance(data, dict) and not data.get("is_realtime", False):
-            realtime = data.get("realtime")
-            if isinstance(realtime, dict) and not realtime.get("api_key"):
-                data.pop("realtime", None)
-        return data

api/schemas/workflow.py

@@ -15,8 +15,12 @@ class WorkflowRunResponseSchema(BaseModel):
     is_completed: bool
     transcript_url: str | None
     recording_url: str | None
+    user_recording_url: str | None = None
+    bot_recording_url: str | None = None
     transcript_public_url: str | None = None
     recording_public_url: str | None = None
+    user_recording_public_url: str | None = None
+    bot_recording_public_url: str | None = None
     public_access_token: str | None = None
     cost_info: Dict[str, Any] | None
     usage_info: Dict[str, Any] | None = None

api/services/auth/depends.py

@@ -1,7 +1,7 @@
 from typing import Annotated, Optional
 
 import httpx
-from fastapi import Header, HTTPException, Query, WebSocket
+from fastapi import Depends, Header, HTTPException, Query, WebSocket
 from loguru import logger
 from pydantic import ValidationError
 
@@ -9,9 +9,10 @@ from api.constants import AUTH_PROVIDER, DOGRAH_MPS_SECRET_KEY, MPS_API_URL
 from api.db import db_client
 from api.db.models import UserModel
 from api.enums import PostHogEvent
-from api.schemas.user_configuration import UserConfiguration
+from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
 from api.services.auth.stack_auth import stackauth
 from api.services.configuration.registry import ServiceProviders
+from api.services.mps_billing import ensure_hosted_mps_billing_account_v2
 from api.services.posthog_client import capture_event
 from api.utils.auth import decode_jwt_token
 
@@ -110,6 +111,19 @@ async def get_user(
             # This prevents race conditions where multiple concurrent requests
             # might try to create configurations
             if org_was_created:
+                try:
+                    await ensure_hosted_mps_billing_account_v2(
+                        organization.id,
+                        created_by=str(stack_user["id"]),
+                    )
+                except Exception:
+                    logger.warning(
+                        "Failed to initialize hosted MPS billing account for "
+                        "organization {}",
+                        organization.id,
+                        exc_info=True,
+                    )
+
                 existing_cfg = await db_client.get_user_configurations(user_model.id)
                 if not (existing_cfg.llm or existing_cfg.tts or existing_cfg.stt):
                     mps_config = await create_user_configuration_with_mps_key(
@@ -119,6 +133,19 @@ async def get_user(
                         await db_client.update_user_configuration(
                             user_model.id, mps_config
                         )
+                        from api.enums import OrganizationConfigurationKey
+                        from api.services.configuration.ai_model_configuration import (
+                            convert_legacy_ai_model_configuration_to_v2,
+                        )
+
+                        model_config_v2 = convert_legacy_ai_model_configuration_to_v2(
+                            mps_config
+                        )
+                        await db_client.upsert_configuration(
+                            organization.id,
+                            OrganizationConfigurationKey.MODEL_CONFIGURATION_V2.value,
+                            model_config_v2.model_dump(mode="json", exclude_none=True),
+                        )
 
     except Exception as exc:
         raise HTTPException(
@@ -129,6 +156,14 @@ async def get_user(
     return user_model
 
 
+async def get_user_with_selected_organization(
+    user: Annotated[UserModel, Depends(get_user)],
+) -> UserModel:
+    if not user.selected_organization_id:
+        raise HTTPException(status_code=400, detail="No organization selected")
+    return user
+
+
 async def _handle_oss_auth(authorization: str | None) -> UserModel:
     """
     Handle authentication for OSS deployment mode.
@@ -192,7 +227,7 @@ async def _handle_api_key_auth(api_key: str) -> UserModel:
 
 async def create_user_configuration_with_mps_key(
     user_id: int, organization_id: int, user_provider_id: str
-) -> Optional[UserConfiguration]:
+) -> Optional[EffectiveAIModelConfiguration]:
     """Create user configuration using MPS service key.
 
     Args:
@@ -201,7 +236,7 @@ async def create_user_configuration_with_mps_key(
         user_provider_id: The user's provider ID (for created_by field)
 
     Returns:
-        UserConfiguration with MPS-provided API keys or None if failed
+        EffectiveAIModelConfiguration with MPS-provided API keys or None if failed
     """
 
     async with httpx.AsyncClient() as client:
@@ -211,7 +246,7 @@ async def create_user_configuration_with_mps_key(
             response = await client.post(
                 f"{MPS_API_URL}/api/v1/service-keys/",
                 json={
-                    "name": f"Default Dograh Model Service Key",
+                    "name": "Default Dograh Model Service Key",
                     "description": "Auto-generated key for OSS user",
                     "expires_in_days": 7,  # Short-lived for OSS
                     "created_by": user_provider_id,
@@ -229,7 +264,7 @@ async def create_user_configuration_with_mps_key(
             response = await client.post(
                 f"{MPS_API_URL}/api/v1/service-keys/",
                 json={
-                    "name": f"Default Dograh Model Service Key",
+                    "name": "Default Dograh Model Service Key",
                     "description": f"Auto-generated key for organization {organization_id}",
                     "organization_id": organization_id,
                     "expires_in_days": 90,  # Longer-lived for authenticated users
@@ -264,8 +299,8 @@ async def create_user_configuration_with_mps_key(
                         "model": "default",
                     },
                 }
-                user_config = UserConfiguration(**configuration)
-                return user_config
+                effective_config = EffectiveAIModelConfiguration(**configuration)
+                return effective_config
         else:
             logger.warning(
                 f"Failed to get MPS service key: {response.status_code} - {response.text}"

api/services/campaign/campaign_call_dispatcher.py

@@ -15,6 +15,7 @@ from api.services.campaign.errors import (
     PhoneNumberPoolExhaustedError,
 )
 from api.services.campaign.rate_limiter import rate_limiter
+from api.services.quota_service import authorize_workflow_run_start
 from api.utils.common import get_backend_endpoints
 
 if TYPE_CHECKING:
@@ -339,6 +340,41 @@ class CampaignCallDispatcher:
                 },
             )
 
+        quota_result = await authorize_workflow_run_start(
+            workflow_id=campaign.workflow_id,
+            workflow_run_id=workflow_run.id,
+        )
+        if not quota_result.has_quota:
+            error_message = quota_result.error_message or "Quota exceeded"
+            logger.warning(
+                f"Campaign {campaign.id} quota check failed for workflow run "
+                f"{workflow_run.id}: {error_message}"
+            )
+            await db_client.update_workflow_run(
+                run_id=workflow_run.id,
+                is_completed=True,
+                state=WorkflowRunState.COMPLETED.value,
+                gathered_context={"error": error_message},
+            )
+
+            mapping = await rate_limiter.get_workflow_slot_mapping(workflow_run.id)
+            if mapping:
+                org_id, mapped_slot_id = mapping
+                await rate_limiter.release_concurrent_slot(org_id, mapped_slot_id)
+                await rate_limiter.delete_workflow_slot_mapping(workflow_run.id)
+
+            from_number_mapping = await rate_limiter.get_workflow_from_number_mapping(
+                workflow_run.id
+            )
+            if from_number_mapping:
+                fn_org_id, fn_number, fn_tcid = from_number_mapping
+                await rate_limiter.release_from_number(
+                    fn_org_id, fn_number, telephony_configuration_id=fn_tcid
+                )
+                await rate_limiter.delete_workflow_from_number_mapping(workflow_run.id)
+
+            raise ValueError(error_message)
+
         # Initiate call via telephony provider
         try:
             # Construct webhook URL with parameters

api/services/configuration/ai_model_configuration.py

@@ -0,0 +1,484 @@
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass
+from typing import Literal
+
+from loguru import logger
+from pydantic import ValidationError
+from sqlalchemy import select, update
+from sqlalchemy.orm import selectinload
+
+from api.constants import MPS_API_URL
+from api.db import db_client
+from api.db.models import WorkflowDefinitionModel, WorkflowModel
+from api.enums import OrganizationConfigurationKey
+from api.schemas.ai_model_configuration import (
+    DOGRAH_DEFAULT_LANGUAGE,
+    DOGRAH_DEFAULT_VOICE,
+    DOGRAH_SPEED_OPTIONS,
+    BYOKAIModelConfiguration,
+    BYOKPipelineAIModelConfiguration,
+    BYOKRealtimeAIModelConfiguration,
+    DograhManagedAIModelConfiguration,
+    EffectiveAIModelConfiguration,
+    OrganizationAIModelConfigurationV2,
+    compile_ai_model_configuration_v2,
+)
+from api.services.configuration.masking import (
+    SERVICE_SECRET_FIELDS,
+    contains_masked_key,
+    mask_key,
+    resolve_masked_api_keys,
+)
+from api.services.configuration.registry import ServiceProviders
+from api.services.configuration.resolve import resolve_effective_config
+
+AIModelConfigurationSource = Literal["organization_v2", "legacy_user_v1", "empty"]
+WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY = "model_configuration_v2_override"
+
+
+@dataclass
+class ResolvedAIModelConfiguration:
+    effective: EffectiveAIModelConfiguration
+    source: AIModelConfigurationSource
+    organization_configuration: OrganizationAIModelConfigurationV2 | None = None
+
+
+@dataclass
+class WorkflowAIModelConfigurationMigrationResult:
+    workflow_count: int = 0
+    definition_count: int = 0
+    workflow_ids: list[int] | None = None
+
+
+async def get_resolved_ai_model_configuration(
+    *,
+    user_id: int | None,
+    organization_id: int | None,
+) -> ResolvedAIModelConfiguration:
+    organization_configuration = await get_organization_ai_model_configuration_v2(
+        organization_id
+    )
+    if organization_configuration is not None:
+        return ResolvedAIModelConfiguration(
+            effective=compile_ai_model_configuration_v2(organization_configuration),
+            source="organization_v2",
+            organization_configuration=organization_configuration,
+        )
+
+    if user_id is None:
+        return ResolvedAIModelConfiguration(
+            effective=EffectiveAIModelConfiguration(),
+            source="empty",
+        )
+
+    legacy = await db_client.get_user_configurations(user_id)
+    return ResolvedAIModelConfiguration(
+        effective=legacy,
+        source="legacy_user_v1" if _has_model_services(legacy) else "empty",
+    )
+
+
+async def get_effective_ai_model_configuration_for_workflow(
+    *,
+    user_id: int | None,
+    organization_id: int | None,
+    workflow_configurations: dict | None,
+) -> EffectiveAIModelConfiguration:
+    workflow_configurations = workflow_configurations or {}
+    v2_override = workflow_configurations.get(
+        WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY
+    )
+    if v2_override:
+        return compile_ai_model_configuration_v2(
+            OrganizationAIModelConfigurationV2.model_validate(v2_override)
+        )
+
+    resolved_config = await get_resolved_ai_model_configuration(
+        user_id=user_id,
+        organization_id=organization_id,
+    )
+    return resolve_effective_config(
+        resolved_config.effective,
+        workflow_configurations.get("model_overrides"),
+    )
+
+
+async def get_organization_ai_model_configuration_v2(
+    organization_id: int | None,
+) -> OrganizationAIModelConfigurationV2 | None:
+    if organization_id is None:
+        return None
+    row = await db_client.get_configuration(
+        organization_id,
+        OrganizationConfigurationKey.MODEL_CONFIGURATION_V2.value,
+    )
+    if row is None or not row.value:
+        return None
+    try:
+        return OrganizationAIModelConfigurationV2.model_validate(row.value)
+    except ValidationError as exc:
+        logger.warning(
+            "Invalid org AI model configuration v2 for organization "
+            f"{organization_id}: {exc}. Falling back to legacy configuration."
+        )
+        return None
+
+
+async def upsert_organization_ai_model_configuration_v2(
+    organization_id: int,
+    configuration: OrganizationAIModelConfigurationV2,
+) -> OrganizationAIModelConfigurationV2:
+    await db_client.upsert_configuration(
+        organization_id,
+        OrganizationConfigurationKey.MODEL_CONFIGURATION_V2.value,
+        configuration.model_dump(mode="json", exclude_none=True),
+    )
+    return configuration
+
+
+async def migrate_workflow_model_configurations_to_v2(
+    *,
+    organization_id: int,
+    fallback_user_config: EffectiveAIModelConfiguration,
+) -> WorkflowAIModelConfigurationMigrationResult:
+    workflows = await _list_workflows_for_model_configuration_migration(organization_id)
+    owner_configs: dict[int, EffectiveAIModelConfiguration] = {}
+    workflow_updates: list[tuple[int, dict]] = []
+    definition_updates: list[tuple[int, dict]] = []
+    migrated_workflow_ids: set[int] = set()
+
+    for workflow in workflows:
+        base_config = fallback_user_config
+        if workflow.user_id is not None:
+            if workflow.user_id not in owner_configs:
+                owner_configs[
+                    workflow.user_id
+                ] = await db_client.get_user_configurations(workflow.user_id)
+            base_config = owner_configs[workflow.user_id]
+
+        workflow_configs, workflow_changed = (
+            migrate_workflow_configuration_model_override_to_v2(
+                workflow.workflow_configurations,
+                base_config,
+            )
+        )
+        if workflow_changed:
+            workflow_updates.append((workflow.id, workflow_configs))
+            migrated_workflow_ids.add(workflow.id)
+
+        for definition in workflow.definitions:
+            definition_configs, definition_changed = (
+                migrate_workflow_configuration_model_override_to_v2(
+                    definition.workflow_configurations,
+                    base_config,
+                )
+            )
+            if definition_changed:
+                definition_updates.append((definition.id, definition_configs))
+                migrated_workflow_ids.add(workflow.id)
+
+    if workflow_updates or definition_updates:
+        async with db_client.async_session() as session:
+            for workflow_id, workflow_configs in workflow_updates:
+                await session.execute(
+                    update(WorkflowModel)
+                    .where(WorkflowModel.id == workflow_id)
+                    .values(workflow_configurations=workflow_configs)
+                )
+            for definition_id, definition_configs in definition_updates:
+                await session.execute(
+                    update(WorkflowDefinitionModel)
+                    .where(WorkflowDefinitionModel.id == definition_id)
+                    .values(workflow_configurations=definition_configs)
+                )
+            await session.commit()
+
+    return WorkflowAIModelConfigurationMigrationResult(
+        workflow_count=len(migrated_workflow_ids),
+        definition_count=len(definition_updates),
+        workflow_ids=sorted(migrated_workflow_ids),
+    )
+
+
+def migrate_workflow_configuration_model_override_to_v2(
+    workflow_configurations: dict | None,
+    base_config: EffectiveAIModelConfiguration,
+) -> tuple[dict, bool]:
+    if not isinstance(workflow_configurations, dict):
+        return {}, False
+
+    migrated = copy.deepcopy(workflow_configurations)
+    model_overrides = migrated.get("model_overrides")
+    existing_v2_override = migrated.get(WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY)
+    if not isinstance(model_overrides, dict):
+        if "model_overrides" in migrated:
+            migrated.pop("model_overrides", None)
+            return migrated, True
+        return migrated, False
+
+    if not existing_v2_override:
+        effective = resolve_effective_config(base_config, model_overrides)
+        v2_override = convert_legacy_ai_model_configuration_to_v2(effective)
+        migrated[WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY] = v2_override.model_dump(
+            mode="json", exclude_none=True
+        )
+    migrated.pop("model_overrides", None)
+    return migrated, True
+
+
+def merge_ai_model_configuration_v2_secrets(
+    incoming: OrganizationAIModelConfigurationV2,
+    existing: OrganizationAIModelConfigurationV2 | None,
+) -> OrganizationAIModelConfigurationV2:
+    if existing is None:
+        return incoming
+
+    incoming_dict = incoming.model_dump(mode="json", exclude_none=True)
+    existing_dict = existing.model_dump(mode="json", exclude_none=True)
+
+    if incoming_dict.get("mode") == "dograh" and existing_dict.get("mode") == "dograh":
+        incoming_dograh = incoming_dict.get("dograh") or {}
+        existing_dograh = existing_dict.get("dograh") or {}
+        incoming_key = incoming_dograh.get("api_key")
+        existing_key = existing_dograh.get("api_key")
+        if incoming_key and existing_key and contains_masked_key(incoming_key):
+            incoming_dograh["api_key"] = resolve_masked_api_keys(
+                incoming_key,
+                existing_key,
+            )
+
+    if incoming_dict.get("mode") == "byok" and existing_dict.get("mode") == "byok":
+        _merge_byok_secret_fields(incoming_dict.get("byok"), existing_dict.get("byok"))
+
+    return OrganizationAIModelConfigurationV2.model_validate(incoming_dict)
+
+
+def check_for_masked_keys_in_ai_model_configuration_v2(
+    configuration: OrganizationAIModelConfigurationV2,
+) -> None:
+    data = configuration.model_dump(mode="json", exclude_none=True)
+    _raise_if_masked_secret(data)
+
+
+def mask_ai_model_configuration_v2(
+    configuration: OrganizationAIModelConfigurationV2 | None,
+) -> dict | None:
+    if configuration is None:
+        return None
+    data = configuration.model_dump(mode="json", exclude_none=True)
+    _mask_secret_fields(data)
+    return data
+
+
+def convert_legacy_ai_model_configuration_to_v2(
+    configuration: EffectiveAIModelConfiguration,
+) -> OrganizationAIModelConfigurationV2:
+    dograh_key = _first_dograh_api_key(configuration)
+    if dograh_key:
+        return _convert_any_dograh_legacy_configuration(configuration, dograh_key)
+
+    if configuration.is_realtime:
+        if configuration.realtime is None or configuration.llm is None:
+            raise ValueError("Realtime legacy configuration is incomplete")
+        return OrganizationAIModelConfigurationV2(
+            mode="byok",
+            byok=BYOKAIModelConfiguration(
+                mode="realtime",
+                realtime=BYOKRealtimeAIModelConfiguration(
+                    realtime=configuration.realtime,
+                    llm=configuration.llm,
+                    embeddings=configuration.embeddings,
+                ),
+            ),
+        )
+
+    if (
+        configuration.llm is None
+        or configuration.tts is None
+        or configuration.stt is None
+    ):
+        raise ValueError("Pipeline legacy configuration is incomplete")
+    return OrganizationAIModelConfigurationV2(
+        mode="byok",
+        byok=BYOKAIModelConfiguration(
+            mode="pipeline",
+            pipeline=BYOKPipelineAIModelConfiguration(
+                llm=configuration.llm,
+                tts=configuration.tts,
+                stt=configuration.stt,
+                embeddings=configuration.embeddings,
+            ),
+        ),
+    )
+
+
+def dograh_embeddings_base_url() -> str:
+    return f"{MPS_API_URL}/api/v1/llm"
+
+
+def apply_managed_embeddings_base_url(
+    *,
+    provider: str | None,
+    base_url: str | None,
+) -> str | None:
+    if provider == ServiceProviders.DOGRAH.value or provider == ServiceProviders.DOGRAH:
+        return dograh_embeddings_base_url()
+    return base_url
+
+
+def _merge_byok_secret_fields(incoming_byok: dict | None, existing_byok: dict | None):
+    if not isinstance(incoming_byok, dict) or not isinstance(existing_byok, dict):
+        return
+    incoming_mode = incoming_byok.get("mode")
+    existing_mode = existing_byok.get("mode")
+    if incoming_mode != existing_mode:
+        return
+    section_names = (
+        ("llm", "tts", "stt", "embeddings")
+        if incoming_mode == "pipeline"
+        else ("realtime", "llm", "embeddings")
+    )
+    incoming_container = incoming_byok.get(incoming_mode)
+    existing_container = existing_byok.get(existing_mode)
+    if not isinstance(incoming_container, dict) or not isinstance(
+        existing_container, dict
+    ):
+        return
+    for section_name in section_names:
+        incoming_section = incoming_container.get(section_name)
+        existing_section = existing_container.get(section_name)
+        if isinstance(incoming_section, dict) and isinstance(existing_section, dict):
+            _merge_service_secret_fields(incoming_section, existing_section)
+
+
+async def _list_workflows_for_model_configuration_migration(
+    organization_id: int,
+) -> list[WorkflowModel]:
+    async with db_client.async_session() as session:
+        result = await session.execute(
+            select(WorkflowModel)
+            .options(selectinload(WorkflowModel.definitions))
+            .where(WorkflowModel.organization_id == organization_id)
+        )
+        return list(result.scalars().unique().all())
+
+
+def _merge_service_secret_fields(incoming: dict, existing: dict):
+    if (
+        incoming.get("provider") is not None
+        and existing.get("provider") is not None
+        and incoming.get("provider") != existing.get("provider")
+    ):
+        return
+    for secret_field in SERVICE_SECRET_FIELDS:
+        if secret_field not in existing:
+            continue
+        incoming_secret = incoming.get(secret_field)
+        existing_secret = existing[secret_field]
+        if incoming_secret is None:
+            incoming[secret_field] = existing_secret
+        elif contains_masked_key(incoming_secret):
+            incoming[secret_field] = resolve_masked_api_keys(
+                incoming_secret,
+                existing_secret,
+            )
+
+
+def _raise_if_masked_secret(value):
+    if isinstance(value, dict):
+        for key, nested in value.items():
+            if key in SERVICE_SECRET_FIELDS and contains_masked_key(nested):
+                raise ValueError(
+                    f"The {key} appears to be masked. Please provide the actual "
+                    "value, not the masked value."
+                )
+            _raise_if_masked_secret(nested)
+    elif isinstance(value, list):
+        for item in value:
+            _raise_if_masked_secret(item)
+
+
+def _mask_secret_fields(value):
+    if isinstance(value, dict):
+        for key, nested in list(value.items()):
+            if key in SERVICE_SECRET_FIELDS and nested:
+                value[key] = _mask_secret_value(nested)
+            else:
+                _mask_secret_fields(nested)
+    elif isinstance(value, list):
+        for item in value:
+            _mask_secret_fields(item)
+
+
+def _mask_secret_value(value):
+    if isinstance(value, list):
+        return [mask_key(item) for item in value]
+    return mask_key(value)
+
+
+def _has_model_services(configuration: EffectiveAIModelConfiguration) -> bool:
+    return any(
+        service is not None
+        for service in (
+            configuration.llm,
+            configuration.tts,
+            configuration.stt,
+            configuration.embeddings,
+            configuration.realtime,
+        )
+    )
+
+
+def _convert_any_dograh_legacy_configuration(
+    configuration: EffectiveAIModelConfiguration,
+    dograh_key: str,
+) -> OrganizationAIModelConfigurationV2:
+    speed = getattr(configuration.tts, "speed", 1.0)
+    if speed not in DOGRAH_SPEED_OPTIONS:
+        speed = 1.0
+    return OrganizationAIModelConfigurationV2(
+        mode="dograh",
+        dograh=DograhManagedAIModelConfiguration(
+            api_key=dograh_key,
+            voice=getattr(configuration.tts, "voice", DOGRAH_DEFAULT_VOICE)
+            or DOGRAH_DEFAULT_VOICE,
+            speed=speed,
+            language=getattr(configuration.stt, "language", DOGRAH_DEFAULT_LANGUAGE)
+            or DOGRAH_DEFAULT_LANGUAGE,
+        ),
+    )
+
+
+def _first_dograh_api_key(configuration: EffectiveAIModelConfiguration) -> str | None:
+    for service in (
+        configuration.llm,
+        configuration.tts,
+        configuration.stt,
+        configuration.embeddings,
+        configuration.realtime,
+    ):
+        if service is None or _provider(service) != ServiceProviders.DOGRAH:
+            continue
+        try:
+            return _single_api_key(service)
+        except ValueError:
+            continue
+    return None
+
+
+def _provider(service):
+    return getattr(service, "provider", None)
+
+
+def _single_api_key(service) -> str:
+    if hasattr(service, "get_all_api_keys"):
+        keys = service.get_all_api_keys()
+        if len(keys) != 1:
+            raise ValueError("Expected exactly one API key")
+        return keys[0]
+    key = getattr(service, "api_key", None)
+    if not key:
+        raise ValueError("Expected an API key")
+    return key

api/services/configuration/check_validity.py

@@ -9,8 +9,8 @@ from groq import Groq
 #     from pyneuphonic import Neuphonic
 # except ImportError:
 #     Neuphonic = None
-from api.schemas.user_configuration import (
-    UserConfiguration,
+from api.schemas.ai_model_configuration import (
+    EffectiveAIModelConfiguration,
 )
 from api.services.configuration.registry import ServiceConfig, ServiceProviders
 from api.services.mps_service_key_client import mps_service_key_client
@@ -51,6 +51,7 @@ class UserConfigurationValidator:
             ServiceProviders.CAMB.value: self._check_camb_api_key,
             ServiceProviders.AWS_BEDROCK.value: self._check_aws_bedrock_api_key,
             ServiceProviders.SPEACHES.value: self._check_speaches_api_key,
+            ServiceProviders.HUGGINGFACE.value: self._check_huggingface_api_key,
             ServiceProviders.GOOGLE_VERTEX.value: self._check_google_vertex_llm_api_key,
             ServiceProviders.OPENAI_REALTIME.value: self._check_openai_api_key,
             ServiceProviders.GROK_REALTIME.value: self._check_grok_realtime_api_key,
@@ -62,11 +63,12 @@ class UserConfigurationValidator:
             ServiceProviders.GLADIA.value: self._check_gladia_api_key,
             ServiceProviders.RIME.value: self._check_rime_api_key,
             ServiceProviders.MINIMAX.value: self._check_minimax_api_key,
+            ServiceProviders.SMALLEST.value: self._check_smallest_api_key,
         }
 
     async def validate(
         self,
-        configuration: UserConfiguration,
+        configuration: EffectiveAIModelConfiguration,
         organization_id: Optional[int] = None,
         created_by: Optional[str] = None,
     ) -> APIKeyStatusResponse:
@@ -77,21 +79,21 @@ class UserConfigurationValidator:
         status_list = []
 
         status_list.extend(self._validate_service(configuration.llm, "llm"))
-        status_list.extend(self._validate_service(configuration.stt, "stt"))
-        status_list.extend(self._validate_service(configuration.tts, "tts"))
-        # Embeddings is optional - only validate if configured
-        status_list.extend(
-            self._validate_service(
-                configuration.embeddings, "embeddings", required=False
-            )
-        )
-        # Realtime is optional - only validate if is_realtime is enabled
         if configuration.is_realtime:
             status_list.extend(
                 self._validate_service(
                     configuration.realtime, "realtime", required=True
                 )
             )
+        else:
+            status_list.extend(self._validate_service(configuration.stt, "stt"))
+            status_list.extend(self._validate_service(configuration.tts, "tts"))
+        # Embeddings is optional - only validate if configured
+        status_list.extend(
+            self._validate_service(
+                configuration.embeddings, "embeddings", required=False
+            )
+        )
 
         if status_list:
             raise ValueError(status_list)
@@ -388,6 +390,14 @@ class UserConfigurationValidator:
             raise ValueError("base_url is required for Speaches services")
         return True
 
+    def _check_huggingface_api_key(self, model: str, api_key: str) -> bool:
+        if not api_key.startswith("hf_"):
+            raise ValueError(
+                "Invalid Hugging Face API token format. Use a token that starts with "
+                "'hf_' and has Inference Providers permission."
+            )
+        return True
+
     def _check_google_vertex_realtime_api_key(self, model: str, service_config) -> bool:
         if not getattr(service_config, "project_id", None):
             raise ValueError("project_id is required for Google Vertex Realtime")
@@ -417,6 +427,7 @@ class UserConfigurationValidator:
         return True
 
     def _check_minimax_api_key(self, model: str, api_key: str) -> bool:
-        # MiniMax doesn't publish a cheap key-validation endpoint; trust the key
-        # at save time and surface auth errors at first call (same as Rime/Sarvam).
+        return True
+
+    def _check_smallest_api_key(self, model: str, api_key: str) -> bool:
         return True

api/services/configuration/masking.py

@@ -12,7 +12,7 @@ The rules are simple:
 import copy
 from typing import Any, Dict, Optional
 
-from api.schemas.user_configuration import UserConfiguration
+from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
 from api.services.configuration.registry import ServiceConfig
 from api.services.integrations import get_node_secret_fields
 
@@ -31,7 +31,7 @@ def contains_masked_key(value: str | list[str] | None) -> bool:
     return any(MASK_MARKER in k for k in keys)
 
 
-def check_for_masked_keys(config: "UserConfiguration") -> None:
+def check_for_masked_keys(config: "EffectiveAIModelConfiguration") -> None:
     """Raise ValueError if any service in *config* still has a masked secret."""
     for field in ("llm", "tts", "stt", "embeddings", "realtime"):
         service = getattr(config, field, None)
@@ -111,7 +111,7 @@ def resolve_masked_api_keys(
 
 
 # ---------------------------------------------------------------------------
-# High-level helpers for UserConfiguration objects
+# High-level helpers for EffectiveAIModelConfiguration objects
 # ---------------------------------------------------------------------------
 
 
@@ -129,7 +129,7 @@ def _mask_service(service_cfg: Optional[ServiceConfig]) -> Optional[Dict[str, An
     return data
 
 
-def mask_user_config(config: UserConfiguration) -> Dict[str, Any]:
+def mask_user_config(config: EffectiveAIModelConfiguration) -> Dict[str, Any]:
     """Return a JSON-serialisable dict of *config* with every api_key masked."""
 
     return {
@@ -151,21 +151,35 @@ def mask_workflow_configurations(config: Optional[Dict]) -> Optional[Dict]:
 
     masked = copy.deepcopy(config)
     model_overrides = masked.get("model_overrides")
-    if not isinstance(model_overrides, dict):
-        return masked
+    if isinstance(model_overrides, dict):
+        for section in MODEL_OVERRIDE_FIELDS:
+            override = model_overrides.get(section)
+            if not isinstance(override, dict):
+                continue
+            for secret_field in SERVICE_SECRET_FIELDS:
+                raw = override.get(secret_field)
+                if raw:
+                    override[secret_field] = _mask_secret_value(raw)
 
-    for section in MODEL_OVERRIDE_FIELDS:
-        override = model_overrides.get(section)
-        if not isinstance(override, dict):
-            continue
-        for secret_field in SERVICE_SECRET_FIELDS:
-            raw = override.get(secret_field)
-            if raw:
-                override[secret_field] = _mask_secret_value(raw)
+    v2_override = masked.get("model_configuration_v2_override")
+    if isinstance(v2_override, dict):
+        _mask_nested_service_secrets(v2_override)
 
     return masked
 
 
+def _mask_nested_service_secrets(value):
+    if isinstance(value, dict):
+        for key, nested in list(value.items()):
+            if key in SERVICE_SECRET_FIELDS and nested:
+                value[key] = _mask_secret_value(nested)
+            else:
+                _mask_nested_service_secrets(nested)
+    elif isinstance(value, list):
+        for item in value:
+            _mask_nested_service_secrets(item)
+
+
 # ---------------------------------------------------------------------------
 # Workflow definition helpers – mask / merge node API keys
 # ---------------------------------------------------------------------------

api/services/configuration/merge.py

@@ -7,7 +7,7 @@ stored, while honouring masked API keys.
 import copy
 from typing import Dict
 
-from api.schemas.user_configuration import UserConfiguration
+from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
 from api.services.configuration.masking import (
     MODEL_OVERRIDE_FIELDS,
     SERVICE_SECRET_FIELDS,
@@ -66,9 +66,9 @@ def _merge_service_secret_fields(
 
 
 def merge_user_configurations(
-    existing: UserConfiguration, incoming_partial: Dict[str, dict]
-) -> UserConfiguration:
-    """Merge *incoming_partial* onto *existing* and return a new UserConfiguration.
+    existing: EffectiveAIModelConfiguration, incoming_partial: Dict[str, dict]
+) -> EffectiveAIModelConfiguration:
+    """Merge *incoming_partial* onto *existing* and return a new EffectiveAIModelConfiguration.
 
     *incoming_partial* is the body of the PUT request (already `model_dump()`ed or
     extracted via Pydantic `model_dump`).
@@ -113,7 +113,7 @@ def merge_user_configurations(
     if "timezone" in incoming_partial:
         merged["timezone"] = incoming_partial["timezone"]
 
-    return UserConfiguration.model_validate(merged)
+    return EffectiveAIModelConfiguration.model_validate(merged)
 
 
 def merge_workflow_configuration_secrets(

api/services/configuration/options/__init__.py

@@ -9,7 +9,13 @@ from .azure import (
     AZURE_SPEECH_TTS_LANGUAGES,
     AZURE_SPEECH_TTS_VOICES,
 )
-from .deepgram import DEEPGRAM_LANGUAGES, DEEPGRAM_STT_MODELS
+from .deepgram import (
+    DEEPGRAM_FLUX_MODELS,
+    DEEPGRAM_FLUX_MULTILINGUAL_LANGUAGE_OPTIONS,
+    DEEPGRAM_FLUX_MULTILINGUAL_LANGUAGES,
+    DEEPGRAM_LANGUAGES,
+    DEEPGRAM_STT_MODELS,
+)
 from .gladia import GLADIA_STT_LANGUAGES, GLADIA_STT_MODELS
 from .google import (
     GOOGLE_MODELS,
@@ -35,6 +41,12 @@ from .sarvam import (
     SARVAM_V2_VOICES,
     SARVAM_V3_VOICES,
 )
+from .smallest import (
+    SMALLEST_TTS_LANGUAGES,
+    SMALLEST_TTS_MODELS,
+    SMALLEST_TTS_PRO_VOICES,
+    SMALLEST_TTS_VOICES,
+)
 from .speechmatics import SPEECHMATICS_STT_LANGUAGES
 
 __all__ = [
@@ -47,6 +59,9 @@ __all__ = [
     "AZURE_SPEECH_STT_LANGUAGES",
     "AZURE_SPEECH_TTS_LANGUAGES",
     "AZURE_SPEECH_TTS_VOICES",
+    "DEEPGRAM_FLUX_MODELS",
+    "DEEPGRAM_FLUX_MULTILINGUAL_LANGUAGES",
+    "DEEPGRAM_FLUX_MULTILINGUAL_LANGUAGE_OPTIONS",
     "DEEPGRAM_LANGUAGES",
     "DEEPGRAM_STT_MODELS",
     "GLADIA_STT_LANGUAGES",
@@ -71,5 +86,9 @@ __all__ = [
     "SARVAM_TTS_MODELS",
     "SARVAM_V2_VOICES",
     "SARVAM_V3_VOICES",
+    "SMALLEST_TTS_LANGUAGES",
+    "SMALLEST_TTS_MODELS",
+    "SMALLEST_TTS_PRO_VOICES",
+    "SMALLEST_TTS_VOICES",
     "SPEECHMATICS_STT_LANGUAGES",
 ]

api/services/configuration/options/deepgram.py

@@ -1,4 +1,21 @@
-DEEPGRAM_STT_MODELS = ("nova-3-general", "flux-general-en", "flux-general-multi")
+DEEPGRAM_FLUX_MODELS = ("flux-general-en", "flux-general-multi")
+DEEPGRAM_FLUX_MULTILINGUAL_LANGUAGES = (
+    "de",
+    "en",
+    "es",
+    "fr",
+    "hi",
+    "it",
+    "ja",
+    "nl",
+    "pt",
+    "ru",
+)
+DEEPGRAM_FLUX_MULTILINGUAL_LANGUAGE_OPTIONS = (
+    "multi",
+    *DEEPGRAM_FLUX_MULTILINGUAL_LANGUAGES,
+)
+DEEPGRAM_STT_MODELS = ("nova-3-general", *DEEPGRAM_FLUX_MODELS)
 DEEPGRAM_LANGUAGES = (
     "multi",
     "ar",

api/services/configuration/options/smallest.py

@@ -0,0 +1,45 @@
+SMALLEST_TTS_MODELS = ("lightning_v3.1", "lightning_v3.1_pro")
+SMALLEST_TTS_VOICES = (
+    "sophia",
+    "avery",
+    "liam",
+    "lucas",
+    "olivia",
+    "ryan",
+    "freya",
+    "william",
+    "devansh",
+    "arjun",
+    "niharika",
+    "maya",
+    "dhruv",
+    "mia",
+    "maithili",
+)
+# Premium voices for lightning_v3.1_pro (American, British, Indian accents; English + Hindi only)
+SMALLEST_TTS_PRO_VOICES = (
+    "meher",
+    "rhea",
+    "aviraj",
+    "cressida",
+    "willow",
+    "maverick",
+)
+SMALLEST_TTS_LANGUAGES = (
+    "en",
+    "hi",
+    "fr",
+    "de",
+    "es",
+    "it",
+    "nl",
+    "pl",
+    "ru",
+    "ar",
+    "bn",
+    "gu",
+    "he",
+    "kn",
+    "mr",
+    "ta",
+)

api/services/configuration/registry.py

@@ -14,6 +14,7 @@ from api.services.configuration.options import (
     AZURE_SPEECH_STT_LANGUAGES,
     AZURE_SPEECH_TTS_LANGUAGES,
     AZURE_SPEECH_TTS_VOICES,
+    DEEPGRAM_FLUX_MULTILINGUAL_LANGUAGE_OPTIONS,
     DEEPGRAM_LANGUAGES,
     DEEPGRAM_STT_MODELS,
     GLADIA_STT_LANGUAGES,
@@ -38,6 +39,10 @@ from api.services.configuration.options import (
     SARVAM_TTS_MODELS,
     SARVAM_V2_VOICES,
     SARVAM_V3_VOICES,
+    SMALLEST_TTS_LANGUAGES,
+    SMALLEST_TTS_MODELS,
+    SMALLEST_TTS_PRO_VOICES,
+    SMALLEST_TTS_VOICES,
     SPEECHMATICS_STT_LANGUAGES,
 )
 from api.services.configuration.options.google import GOOGLE_VERTEX_MODELS
@@ -69,6 +74,7 @@ class ServiceProviders(str, Enum):
     CAMB = "camb"
     AWS_BEDROCK = "aws_bedrock"
     SPEACHES = "speaches"
+    HUGGINGFACE = "huggingface"
     ASSEMBLYAI = "assemblyai"
     GLADIA = "gladia"
     RIME = "rime"
@@ -80,6 +86,7 @@ class ServiceProviders(str, Enum):
     GOOGLE_REALTIME = "google_realtime"
     GOOGLE_VERTEX_REALTIME = "google_vertex_realtime"
     AZURE_REALTIME = "azure_realtime"
+    SMALLEST = "smallest"
 
 
 class BaseServiceConfiguration(BaseModel):
@@ -96,6 +103,7 @@ class BaseServiceConfiguration(BaseModel):
         ServiceProviders.DOGRAH,
         ServiceProviders.AWS_BEDROCK,
         ServiceProviders.SPEACHES,
+        ServiceProviders.HUGGINGFACE,
         ServiceProviders.ASSEMBLYAI,
         ServiceProviders.GLADIA,
         ServiceProviders.RIME,
@@ -108,6 +116,7 @@ class BaseServiceConfiguration(BaseModel):
         ServiceProviders.GOOGLE_VERTEX_REALTIME,
         ServiceProviders.AZURE_REALTIME,
         ServiceProviders.SARVAM,
+        ServiceProviders.SMALLEST,
     ]
     api_key: str | list[str]
 
@@ -265,6 +274,11 @@ SPEACHES_PROVIDER_MODEL_CONFIG = provider_model_config(
     ),
     provider_docs_url="https://github.com/speaches-ai/speaches",
 )
+HUGGINGFACE_PROVIDER_MODEL_CONFIG = provider_model_config(
+    "Hugging Face",
+    description="Hosted Hugging Face Inference Providers API for usage-based inference.",
+    provider_docs_url="https://huggingface.co/docs/inference-providers/en/index",
+)
 AZURE_SPEECH_PROVIDER_MODEL_CONFIG = provider_model_config(
     "Azure Speech Services",
     description="Azure Cognitive Services Speech — TTS and STT via the Azure Speech SDK.",
@@ -481,6 +495,35 @@ class SpeachesLLMConfiguration(BaseLLMConfiguration):
     )
 
 
+HUGGINGFACE_LLM_MODELS = [
+    "openai/gpt-oss-120b:cerebras",
+    "deepseek-ai/DeepSeek-R1:fastest",
+    "Qwen/Qwen3-Coder-480B-A35B-Instruct:fastest",
+]
+
+
+@register_llm
+class HuggingFaceLLMConfiguration(BaseLLMConfiguration):
+    model_config = HUGGINGFACE_PROVIDER_MODEL_CONFIG
+    provider: Literal[ServiceProviders.HUGGINGFACE] = ServiceProviders.HUGGINGFACE
+    model: str = Field(
+        default="openai/gpt-oss-120b:cerebras",
+        description="Hugging Face chat-completion model identifier, optionally with provider suffix.",
+        json_schema_extra={
+            "examples": HUGGINGFACE_LLM_MODELS,
+            "allow_custom_input": True,
+        },
+    )
+    base_url: str = Field(
+        default="https://router.huggingface.co/v1",
+        description="Hugging Face OpenAI-compatible chat-completions router base URL.",
+    )
+    bill_to: str | None = Field(
+        default=None,
+        description="Optional Hugging Face organization or user to bill using X-HF-Bill-To.",
+    )
+
+
 MINIMAX_MODELS = [
     "MiniMax-M2.7",
     "MiniMax-M2.7-highspeed",
@@ -751,6 +794,7 @@ LLMConfig = Annotated[
         DograhLLMService,
         AWSBedrockLLMConfiguration,
         SpeachesLLMConfiguration,
+        HuggingFaceLLMConfiguration,
         MiniMaxLLMConfiguration,
         SarvamLLMConfiguration,
     ],
@@ -917,11 +961,12 @@ class DograhTTSService(BaseTTSConfiguration):
     voice: str = Field(
         default="default",
         description="Voice preset.",
+        json_schema_extra={"allow_custom_input": True},
     )
     speed: float = Field(default=1.0, ge=0.5, le=2.0, description="Speed of the voice.")
 
 
-CARTESIA_TTS_MODELS = ["sonic-3"]
+CARTESIA_TTS_MODELS = ["sonic-3.5", "sonic-3"]
 INWORLD_TTS_MODELS = ["inworld-tts-2"]
 INWORLD_TTS_VOICES = ["Ashley"]
 INWORLD_TTS_LANGUAGES = ["en-US"]
@@ -932,7 +977,7 @@ class CartesiaTTSConfiguration(BaseTTSConfiguration):
     model_config = CARTESIA_PROVIDER_MODEL_CONFIG
     provider: Literal[ServiceProviders.CARTESIA] = ServiceProviders.CARTESIA
     model: str = Field(
-        default="sonic-3",
+        default="sonic-3.5",
         description="Cartesia TTS model.",
         json_schema_extra={"examples": CARTESIA_TTS_MODELS},
     )
@@ -947,6 +992,11 @@ class CartesiaTTSConfiguration(BaseTTSConfiguration):
         le=2.0,
         description="Volume multiplier for generated speech.",
     )
+    language: str = Field(
+        default="en",
+        description="Cartesia language code for TTS synthesis (e.g. 'en', 'tr', 'fr', 'de').",
+        json_schema_extra={"allow_custom_input": True},
+    )
 
 
 @register_tts
@@ -1000,9 +1050,10 @@ class SarvamTTSConfiguration(BaseTTSConfiguration):
     )
     voice: str = Field(
         default="anushka",
-        description="Sarvam voice name; must match the selected model's voice list.",
+        description="Sarvam voice name or custom voice ID.",
         json_schema_extra={
             "examples": SARVAM_V2_VOICES,
+            "allow_custom_input": True,
             "model_options": {
                 "bulbul:v2": SARVAM_V2_VOICES,
                 "bulbul:v3": SARVAM_V3_VOICES,
@@ -1014,6 +1065,12 @@ class SarvamTTSConfiguration(BaseTTSConfiguration):
         description="BCP-47 Indian-language code (e.g. hi-IN, en-IN).",
         json_schema_extra={"examples": SARVAM_LANGUAGES},
     )
+    speed: float = Field(
+        default=1.0,
+        ge=0.5,
+        le=2.0,
+        description="Speech speed multiplier.",
+    )
 
 
 CAMB_TTS_MODELS = ["mars-flash", "mars-pro", "mars-instruct"]
@@ -1173,6 +1230,50 @@ class AzureSpeechTTSConfiguration(BaseTTSConfiguration):
     )
 
 
+SMALLEST_PROVIDER_MODEL_CONFIG = provider_model_config(
+    "Smallest AI",
+    description="Smallest AI ultralow-latency TTS (Waves) and STT (Pulse) APIs.",
+    provider_docs_url="https://smallest.ai/docs",
+)
+
+
+@register_tts
+class SmallestAITTSConfiguration(BaseTTSConfiguration):
+    model_config = SMALLEST_PROVIDER_MODEL_CONFIG
+    provider: Literal[ServiceProviders.SMALLEST] = ServiceProviders.SMALLEST
+    model: str = Field(
+        default="lightning_v3.1",
+        description="Smallest AI TTS model. lightning_v3.1_pro is the premium pool (American, British, Indian accents); lightning_v3.1 is the standard pool with 217 voices across 12 languages.",
+        json_schema_extra={"examples": SMALLEST_TTS_MODELS},
+    )
+    voice: str = Field(
+        default="sophia",
+        description="Smallest AI voice ID. Available voices differ by model: lightning_v3.1 has a broad multilingual pool; lightning_v3.1_pro has premium American, British, and Indian accent voices (English + Hindi only).",
+        json_schema_extra={
+            "examples": list(SMALLEST_TTS_VOICES),
+            "allow_custom_input": True,
+            "model_options": {
+                "lightning_v3.1": list(SMALLEST_TTS_VOICES),
+                "lightning_v3.1_pro": list(SMALLEST_TTS_PRO_VOICES),
+            },
+        },
+    )
+    language: str = Field(
+        default="en",
+        description="ISO 639-1 language code for synthesis.",
+        json_schema_extra={
+            "examples": SMALLEST_TTS_LANGUAGES,
+            "allow_custom_input": True,
+        },
+    )
+    speed: float = Field(
+        default=1.0,
+        ge=0.5,
+        le=2.0,
+        description="Speech speed multiplier (0.5 to 2.0).",
+    )
+
+
 TTSConfig = Annotated[
     Union[
         DeepgramTTSConfiguration,
@@ -1188,6 +1289,7 @@ TTSConfig = Annotated[
         SpeachesTTSConfiguration,
         MiniMaxTTSConfiguration,
         AzureSpeechTTSConfiguration,
+        SmallestAITTSConfiguration,
     ],
     Field(discriminator="provider"),
 ]
@@ -1206,12 +1308,16 @@ class DeepgramSTTConfiguration(BaseSTTConfiguration):
     )
     language: str = Field(
         default="multi",
-        description="Language code; 'multi' enables auto-detect (Nova-3 only).",
+        description=(
+            "Language code. 'multi' enables Nova-3 auto-detect and omits "
+            "language hints for Flux multilingual auto-detect."
+        ),
         json_schema_extra={
             "examples": DEEPGRAM_LANGUAGES,
             "model_options": {
                 "nova-3-general": DEEPGRAM_LANGUAGES,
                 "flux-general-en": ("en",),
+                "flux-general-multi": DEEPGRAM_FLUX_MULTILINGUAL_LANGUAGE_OPTIONS,
             },
         },
     )
@@ -1388,6 +1494,38 @@ class SpeachesSTTConfiguration(BaseSTTConfiguration):
     )
 
 
+HUGGINGFACE_STT_MODELS = [
+    "openai/whisper-large-v3-turbo",
+    "openai/whisper-large-v3",
+]
+
+
+@register_stt
+class HuggingFaceSTTConfiguration(BaseSTTConfiguration):
+    model_config = HUGGINGFACE_PROVIDER_MODEL_CONFIG
+    provider: Literal[ServiceProviders.HUGGINGFACE] = ServiceProviders.HUGGINGFACE
+    model: str = Field(
+        default="openai/whisper-large-v3-turbo",
+        description="Hugging Face ASR model identifier served through Inference Providers.",
+        json_schema_extra={
+            "examples": HUGGINGFACE_STT_MODELS,
+            "allow_custom_input": True,
+        },
+    )
+    base_url: str = Field(
+        default="https://router.huggingface.co/hf-inference",
+        description="Hugging Face Inference Providers router base URL.",
+    )
+    bill_to: str | None = Field(
+        default=None,
+        description="Optional Hugging Face organization or user to bill using X-HF-Bill-To.",
+    )
+    return_timestamps: bool = Field(
+        default=False,
+        description="Request timestamp chunks when supported by the selected provider/model.",
+    )
+
+
 ASSEMBLYAI_STT_MODELS = ["u3-rt-pro"]
 ASSEMBLYAI_STT_LANGUAGES = ["en", "es", "de", "fr", "pt", "it"]
 
@@ -1450,6 +1588,62 @@ class AzureSpeechSTTConfiguration(BaseSTTConfiguration):
     )
 
 
+SMALLEST_STT_MODELS = ["pulse"]
+SMALLEST_STT_LANGUAGES = [
+    "en",
+    "hi",
+    "fr",
+    "de",
+    "es",
+    "it",
+    "nl",
+    "pl",
+    "ru",
+    "pt",
+    "bn",
+    "gu",
+    "kn",
+    "ml",
+    "mr",
+    "ta",
+    "te",
+    "pa",
+    "or",
+    "bg",
+    "cs",
+    "da",
+    "et",
+    "fi",
+    "hu",
+    "lt",
+    "lv",
+    "mt",
+    "ro",
+    "sk",
+    "sv",
+    "uk",
+]
+
+
+@register_stt
+class SmallestAISTTConfiguration(BaseSTTConfiguration):
+    model_config = SMALLEST_PROVIDER_MODEL_CONFIG
+    provider: Literal[ServiceProviders.SMALLEST] = ServiceProviders.SMALLEST
+    model: str = Field(
+        default="pulse",
+        description="Smallest AI STT model. Supports 38 languages with real-time streaming.",
+        json_schema_extra={"examples": SMALLEST_STT_MODELS},
+    )
+    language: str = Field(
+        default="en",
+        description="ISO 639-1 language code for transcription.",
+        json_schema_extra={
+            "examples": SMALLEST_STT_LANGUAGES,
+            "allow_custom_input": True,
+        },
+    )
+
+
 STTConfig = Annotated[
     Union[
         DeepgramSTTConfiguration,
@@ -1460,9 +1654,11 @@ STTConfig = Annotated[
         SpeechmaticsSTTConfiguration,
         SarvamSTTConfiguration,
         SpeachesSTTConfiguration,
+        HuggingFaceSTTConfiguration,
         AssemblyAISTTConfiguration,
         GladiaSTTConfiguration,
         AzureSpeechSTTConfiguration,
+        SmallestAISTTConfiguration,
     ],
     Field(discriminator="provider"),
 ]
@@ -1526,11 +1722,26 @@ class AzureOpenAIEmbeddingsConfiguration(BaseEmbeddingsConfiguration):
     )
 
 
+DOGRAH_EMBEDDING_MODELS = ["default"]
+
+
+@register_embeddings
+class DograhEmbeddingsConfiguration(BaseEmbeddingsConfiguration):
+    model_config = DOGRAH_PROVIDER_MODEL_CONFIG
+    provider: Literal[ServiceProviders.DOGRAH] = ServiceProviders.DOGRAH
+    model: str = Field(
+        default="default",
+        description="Dograh-managed embedding model.",
+        json_schema_extra={"examples": DOGRAH_EMBEDDING_MODELS},
+    )
+
+
 EmbeddingsConfig = Annotated[
     Union[
         OpenAIEmbeddingsConfiguration,
         OpenRouterEmbeddingsConfiguration,
         AzureOpenAIEmbeddingsConfiguration,
+        DograhEmbeddingsConfiguration,
     ],
     Field(discriminator="provider"),
 ]

api/services/configuration/resolve.py

@@ -4,13 +4,13 @@ from __future__ import annotations
 
 import copy
 
-from api.schemas.user_configuration import UserConfiguration
+from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
 from api.services.configuration.registry import (
     REGISTRY,
     ServiceType,
 )
 
-# Maps override key → (UserConfiguration field, ServiceType for registry lookup)
+# Maps override key → (EffectiveAIModelConfiguration field, ServiceType for registry lookup)
 _SECTION_MAP: dict[str, ServiceType] = {
     "llm": ServiceType.LLM,
     "tts": ServiceType.TTS,
@@ -36,7 +36,7 @@ _SECRET_FIELDS = ("api_key", "credentials", "aws_access_key", "aws_secret_key")
 
 def enrich_overrides_with_api_keys(
     model_overrides: dict,
-    user_config: UserConfiguration,
+    user_config: EffectiveAIModelConfiguration,
 ) -> dict:
     """Copy API keys from the global config into model_overrides where missing.
 
@@ -74,9 +74,9 @@ def enrich_overrides_with_api_keys(
 
 
 def resolve_effective_config(
-    user_config: UserConfiguration,
+    user_config: EffectiveAIModelConfiguration,
     model_overrides: dict | None,
-) -> UserConfiguration:
+) -> EffectiveAIModelConfiguration:
     """Deep-merge workflow model_overrides onto global user config.
 
     - If model_overrides is None or empty, returns a copy of user_config unchanged.

api/services/gen_ai/embedding/openai_service.py

@@ -38,6 +38,7 @@ class OpenAIEmbeddingService(BaseEmbeddingService):
         api_key: Optional[str] = None,
         model_id: str = DEFAULT_MODEL_ID,
         base_url: Optional[str] = None,
+        default_headers: Optional[Dict[str, str]] = None,
     ):
         """Initialize the OpenAI embedding service.
 
@@ -60,6 +61,8 @@ class OpenAIEmbeddingService(BaseEmbeddingService):
                     field_name="base_url",
                 )
                 client_kwargs["base_url"] = base_url
+            if default_headers:
+                client_kwargs["default_headers"] = default_headers
             self.client = AsyncOpenAI(**client_kwargs)
             logger.info(f"OpenAI embedding service initialized with model: {model_id}")
         else:

api/services/managed_model_services.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
+from api.services.configuration.registry import ServiceProviders
+
+MPS_CORRELATION_ID_CONTEXT_KEY = "mps_correlation_id"
+
+
+def uses_managed_model_services_v2(
+    ai_model_config: EffectiveAIModelConfiguration | None,
+) -> bool:
+    if (
+        ai_model_config is None
+        or getattr(ai_model_config, "managed_service_version", None) != 2
+    ):
+        return False
+
+    return any(
+        _is_dograh_service(getattr(ai_model_config, section_name, None))
+        for section_name in ("llm", "tts", "stt", "embeddings")
+    )
+
+
+def get_mps_correlation_id(initial_context: dict[str, Any] | None) -> str | None:
+    if not initial_context:
+        return None
+    correlation_id = initial_context.get(MPS_CORRELATION_ID_CONTEXT_KEY)
+    if correlation_id is None:
+        return None
+    return str(correlation_id)
+
+
+async def ensure_mps_correlation_id(
+    *,
+    ai_model_config: EffectiveAIModelConfiguration,
+    workflow_run_id: int,
+    initial_context: dict[str, Any] | None,
+) -> str | None:
+    existing = get_mps_correlation_id(initial_context)
+    if existing:
+        return existing
+
+    if not uses_managed_model_services_v2(ai_model_config):
+        return None
+
+    raise ValueError(
+        "Managed model services v2 requires workflow run authorization before "
+        f"the run starts. Missing correlation id for workflow_run_id={workflow_run_id}."
+    )
+
+
+def _is_dograh_service(service: Any) -> bool:
+    provider = getattr(service, "provider", None)
+    return (
+        provider == ServiceProviders.DOGRAH or provider == ServiceProviders.DOGRAH.value
+    )
+
+
+def get_dograh_service_api_key(
+    ai_model_config: EffectiveAIModelConfiguration,
+) -> str | None:
+    for section_name in ("llm", "tts", "stt", "embeddings"):
+        service = getattr(ai_model_config, section_name, None)
+        if not _is_dograh_service(service):
+            continue
+
+        if hasattr(service, "get_all_api_keys"):
+            keys = service.get_all_api_keys()
+            if keys:
+                return keys[0]
+
+        api_key = getattr(service, "api_key", None)
+        if isinstance(api_key, str) and api_key:
+            return api_key
+
+    return None

api/services/mps_billing.py

@@ -0,0 +1,23 @@
+from typing import Optional
+
+from api.constants import DEPLOYMENT_MODE
+from api.services.mps_service_key_client import mps_service_key_client
+
+
+async def ensure_hosted_mps_billing_account_v2(
+    organization_id: int,
+    *,
+    created_by: Optional[str] = None,
+) -> Optional[dict]:
+    """Ensure hosted orgs have an MPS billing v2 account.
+
+    OSS deployments use legacy per-key quota accounting and do not create MPS
+    billing accounts.
+    """
+    if DEPLOYMENT_MODE == "oss":
+        return None
+
+    return await mps_service_key_client.ensure_billing_account_v2(
+        organization_id=organization_id,
+        created_by=created_by,
+    )

api/services/mps_service_key_client.py

@@ -4,6 +4,7 @@ This client communicates with the Model Proxy Service (MPS) for service key mana
 Service keys are stored and managed entirely in MPS, not in the local database.
 """
 
+import asyncio
 from typing import List, Optional
 
 import httpx
@@ -353,6 +354,277 @@ class MPSServiceKeyClient:
                     response=response,
                 )
 
+    async def create_credit_purchase_url(
+        self,
+        organization_id: int,
+        created_by: Optional[str] = None,
+        return_url: Optional[str] = None,
+        billing_details: Optional[dict] = None,
+    ) -> dict:
+        """Create a short-lived MPS checkout URL for adding organization credits."""
+        payload = {
+            "created_by": created_by,
+            "return_url": return_url,
+            "billing_details": billing_details or {},
+        }
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(
+                f"{self.base_url}/api/v1/billing/accounts/{organization_id}/checkout-sessions",
+                json=payload,
+                headers=self._get_headers(
+                    organization_id=organization_id,
+                    created_by=created_by,
+                ),
+            )
+
+            if response.status_code == 200:
+                return response.json()
+
+            logger.error(
+                "Failed to create MPS credit purchase URL: "
+                f"{response.status_code} - {response.text}"
+            )
+            raise httpx.HTTPStatusError(
+                f"Failed to create MPS credit purchase URL: {response.text}",
+                request=response.request,
+                response=response,
+            )
+
+    async def get_credit_ledger(
+        self,
+        organization_id: int,
+        page: int = 1,
+        limit: int = 50,
+        created_by: Optional[str] = None,
+    ) -> dict:
+        """Get the MPS v2 billing account balance and recent credit ledger."""
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(
+                f"{self.base_url}/api/v1/billing/accounts/{organization_id}/ledger",
+                params={"page": page, "limit": limit},
+                headers=self._get_headers(
+                    organization_id=organization_id,
+                    created_by=created_by,
+                ),
+            )
+
+            if response.status_code == 200:
+                return response.json()
+
+            logger.error(
+                "Failed to get MPS credit ledger: "
+                f"{response.status_code} - {response.text}"
+            )
+            raise httpx.HTTPStatusError(
+                f"Failed to get MPS credit ledger: {response.text}",
+                request=response.request,
+                response=response,
+            )
+
+    async def get_billing_account_status(
+        self,
+        organization_id: int,
+        created_by: Optional[str] = None,
+    ) -> Optional[dict]:
+        """Get an existing MPS v2 billing account without creating one."""
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(
+                f"{self.base_url}/api/v1/billing/accounts/{organization_id}/status",
+                headers=self._get_headers(
+                    organization_id=organization_id,
+                    created_by=created_by,
+                ),
+            )
+
+            if response.status_code == 200:
+                return response.json()
+
+            logger.error(
+                "Failed to get MPS billing account status: "
+                f"{response.status_code} - {response.text}"
+            )
+            raise httpx.HTTPStatusError(
+                f"Failed to get MPS billing account status: {response.text}",
+                request=response.request,
+                response=response,
+            )
+
+    async def ensure_billing_account_v2(
+        self,
+        organization_id: int,
+        created_by: Optional[str] = None,
+    ) -> dict:
+        """Create or return the MPS v2 billing account for an organization."""
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(
+                f"{self.base_url}/api/v1/billing/accounts/{organization_id}/balance",
+                headers=self._get_headers(
+                    organization_id=organization_id,
+                    created_by=created_by,
+                ),
+            )
+
+            if response.status_code == 200:
+                return response.json()
+
+            logger.error(
+                "Failed to ensure MPS billing account v2: "
+                f"{response.status_code} - {response.text}"
+            )
+            raise httpx.HTTPStatusError(
+                f"Failed to ensure MPS billing account v2: {response.text}",
+                request=response.request,
+                response=response,
+            )
+
+    async def authorize_workflow_run_start(
+        self,
+        *,
+        organization_id: int,
+        workflow_run_id: int | None = None,
+        service_key: Optional[str] = None,
+        require_correlation_id: bool = False,
+        minimum_credits: float | None = None,
+        metadata: Optional[dict] = None,
+        created_by: Optional[str] = None,
+    ) -> dict:
+        """Authorize a hosted workflow run and optionally mint its MPS correlation."""
+        payload = {
+            "workflow_run_id": workflow_run_id,
+            "service_key": service_key,
+            "require_correlation_id": require_correlation_id,
+            "metadata": metadata or {},
+        }
+        if minimum_credits is not None:
+            payload["minimum_credits"] = minimum_credits
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(
+                f"{self.base_url}/api/v1/billing/accounts/{organization_id}/run-authorization",
+                json=payload,
+                headers=self._get_headers(
+                    organization_id=organization_id,
+                    created_by=created_by,
+                ),
+            )
+
+            if response.status_code == 200:
+                return response.json()
+
+            logger.error(
+                "Failed to authorize MPS workflow run start: "
+                f"{response.status_code} - {response.text}"
+            )
+            raise httpx.HTTPStatusError(
+                f"Failed to authorize MPS workflow run start: {response.text}",
+                request=response.request,
+                response=response,
+            )
+
+    async def create_correlation_id(
+        self,
+        *,
+        service_key: str,
+        workflow_run_id: int | None = None,
+    ) -> dict:
+        """Mint a server-generated correlation ID for managed model services."""
+        payload: dict[str, int] = {}
+        if workflow_run_id is not None:
+            payload["workflow_run_id"] = workflow_run_id
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(
+                f"{self.base_url}/api/v1/service-keys/correlation-id/self",
+                json=payload,
+                headers={
+                    "Authorization": f"Bearer {service_key}",
+                    "Content-Type": "application/json",
+                },
+            )
+
+            if response.status_code == 200:
+                return response.json()
+
+            logger.error(
+                "Failed to create correlation ID: "
+                f"{response.status_code} - {response.text}"
+            )
+            raise httpx.HTTPStatusError(
+                f"Failed to create correlation ID: {response.text}",
+                request=response.request,
+                response=response,
+            )
+
+    async def report_platform_usage(
+        self,
+        *,
+        organization_id: int,
+        correlation_id: Optional[str] = None,
+        duration_seconds: Optional[float] = None,
+        workflow_run_id: int | None = None,
+        metadata: Optional[dict] = None,
+        max_attempts: int = 3,
+    ) -> dict:
+        """Report hosted Dograh platform usage for a completed workflow run."""
+        if DEPLOYMENT_MODE == "oss":
+            raise ValueError("OSS deployments must not report platform usage to MPS")
+        if not correlation_id and duration_seconds is None:
+            raise ValueError(
+                "Platform usage reports require correlation_id or duration_seconds"
+            )
+
+        payload: dict = {
+            "metadata": metadata or {},
+        }
+        if correlation_id:
+            payload["correlation_id"] = correlation_id
+        if duration_seconds is not None:
+            payload["duration_seconds"] = duration_seconds
+        if workflow_run_id is not None:
+            payload["workflow_run_id"] = workflow_run_id
+
+        max_attempts = max(1, max_attempts)
+        last_response: httpx.Response | None = None
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            for attempt in range(1, max_attempts + 1):
+                response = await client.post(
+                    (
+                        f"{self.base_url}/api/v1/billing/accounts/"
+                        f"{organization_id}/platform-usage"
+                    ),
+                    json=payload,
+                    headers=self._get_headers(organization_id=organization_id),
+                )
+                last_response = response
+
+                if response.status_code == 200:
+                    return response.json()
+
+                usage_not_ready = (
+                    response.status_code == 409 and "usage_not_ready" in response.text
+                )
+                if usage_not_ready and attempt < max_attempts:
+                    await asyncio.sleep(attempt)
+                    continue
+
+                log = logger.warning if usage_not_ready else logger.error
+                log(
+                    "Failed to report platform usage: "
+                    f"{response.status_code} - {response.text}"
+                )
+                raise httpx.HTTPStatusError(
+                    f"Failed to report platform usage: {response.text}",
+                    request=response.request,
+                    response=response,
+                )
+
+        raise httpx.HTTPStatusError(
+            "Failed to report platform usage",
+            request=last_response.request,
+            response=last_response,
+        )
+
     async def transcribe_audio(
         self,
         audio_data: bytes,

api/services/organization_context.py

@@ -0,0 +1,50 @@
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+from api.db import db_client
+from api.db.models import UserModel
+from api.services.configuration.ai_model_configuration import (
+    get_resolved_ai_model_configuration,
+)
+
+
+class OrganizationModelServicesContext(BaseModel):
+    config_source: Literal["organization_v2", "legacy_user_v1", "empty"]
+    has_model_configuration_v2: bool
+    managed_service_version: Optional[int] = None
+    uses_managed_service_v2: bool
+
+
+class OrganizationContextResponse(BaseModel):
+    organization_id: Optional[int] = None
+    organization_provider_id: Optional[str] = None
+    model_services: OrganizationModelServicesContext
+
+
+async def get_organization_context(user: UserModel) -> OrganizationContextResponse:
+    organization_id = user.selected_organization_id
+    organization = (
+        await db_client.get_organization_by_id(organization_id)
+        if organization_id
+        else None
+    )
+
+    resolved = await get_resolved_ai_model_configuration(
+        user_id=user.id,
+        organization_id=organization_id,
+    )
+    managed_service_version = resolved.effective.managed_service_version
+
+    return OrganizationContextResponse(
+        organization_id=organization_id,
+        organization_provider_id=organization.provider_id if organization else None,
+        model_services=OrganizationModelServicesContext(
+            config_source=resolved.source,
+            has_model_configuration_v2=resolved.source == "organization_v2",
+            managed_service_version=managed_service_version,
+            uses_managed_service_v2=(
+                resolved.source == "organization_v2" and managed_service_version == 2
+            ),
+        ),
+    )

api/services/organization_preferences.py

@@ -0,0 +1,62 @@
+from inspect import isawaitable
+
+from loguru import logger
+from pydantic import ValidationError
+
+from api.db import db_client
+from api.enums import OrganizationConfigurationKey
+from api.schemas.organization_preferences import OrganizationPreferences
+
+
+async def get_organization_preferences(
+    organization_id: int | None,
+    db=None,
+) -> OrganizationPreferences:
+    if organization_id is None:
+        return OrganizationPreferences()
+
+    db = db or db_client
+    row = await _get_configuration(
+        db,
+        organization_id,
+        OrganizationConfigurationKey.ORGANIZATION_PREFERENCES.value,
+    )
+    if row is None:
+        row = await _get_configuration(
+            db,
+            organization_id,
+            OrganizationConfigurationKey.MODEL_CONFIGURATION_PREFERENCES.value,
+        )
+    return _parse_preferences(row.value if row is not None else None, organization_id)
+
+
+async def upsert_organization_preferences(
+    organization_id: int,
+    preferences: OrganizationPreferences,
+) -> OrganizationPreferences:
+    await db_client.upsert_configuration(
+        organization_id,
+        OrganizationConfigurationKey.ORGANIZATION_PREFERENCES.value,
+        preferences.model_dump(mode="json", exclude_none=True),
+    )
+    return preferences
+
+
+async def _get_configuration(db, organization_id: int, key: str):
+    row = db.get_configuration(organization_id, key)
+    if isawaitable(row):
+        row = await row
+    return row
+
+
+def _parse_preferences(value, organization_id: int) -> OrganizationPreferences:
+    if not value or not isinstance(value, dict):
+        return OrganizationPreferences()
+    try:
+        return OrganizationPreferences.model_validate(value)
+    except ValidationError as exc:
+        logger.warning(
+            "Invalid organization preferences for organization "
+            f"{organization_id}: {exc}. Returning defaults."
+        )
+        return OrganizationPreferences()

api/services/pipecat/event_handlers.py

@@ -9,8 +9,8 @@ from api.services.integrations import IntegrationRuntimeSession
 from api.services.pipecat.audio_config import AudioConfig
 from api.services.pipecat.audio_playback import play_audio_loop
 from api.services.pipecat.in_memory_buffers import (
-    InMemoryAudioBuffer,
     InMemoryLogsBuffer,
+    InMemoryRecordingBuffers,
 )
 from api.services.pipecat.pipeline_metrics_aggregator import PipelineMetricsAggregator
 from api.services.pipecat.tracing_config import get_trace_url
@@ -40,11 +40,11 @@ async def _capture_call_event(
             "workflow_run_id": workflow_run_id,
             "workflow_id": workflow_run.workflow_id if workflow_run else None,
             "call_type": workflow_run.mode if workflow_run else None,
-            "call_direction": (workflow_run.initial_context or {}).get(
-                "direction", "outbound"
-            )
-            if workflow_run
-            else None,
+            "call_direction": (
+                (workflow_run.initial_context or {}).get("direction", "outbound")
+                if workflow_run
+                else None
+            ),
         }
         if extra_properties:
             properties.update(extra_properties)
@@ -73,7 +73,7 @@ def register_event_handlers(
     """Register all event handlers for transport and task events.
 
     Returns:
-        in_memory_audio_buffer for use by other handlers.
+        In-memory recording buffers for use by other handlers.
     """
     # Initialize in-memory buffers with proper audio configuration
     sample_rate = audio_config.pipeline_sample_rate if audio_config else 16000
@@ -84,7 +84,7 @@ def register_event_handlers(
         f"with sample_rate={sample_rate}Hz, channels={num_channels}"
     )
 
-    in_memory_audio_buffer = InMemoryAudioBuffer(
+    in_memory_audio_buffers = InMemoryRecordingBuffers(
         workflow_run_id=workflow_run_id,
         sample_rate=sample_rate,
         num_channels=num_channels,
@@ -363,14 +363,32 @@ def register_event_handlers(
 
         # Write buffers to temp files and enqueue combined processing task
         audio_temp_path = None
+        user_audio_temp_path = None
+        bot_audio_temp_path = None
         transcript_temp_path = None
 
         try:
-            if not in_memory_audio_buffer.is_empty:
-                audio_temp_path = await in_memory_audio_buffer.write_to_temp_file()
+            if not in_memory_audio_buffers.mixed.is_empty:
+                audio_temp_path = (
+                    await in_memory_audio_buffers.mixed.write_to_temp_file()
+                )
             else:
                 logger.debug("Audio buffer is empty, skipping upload")
 
+            if not in_memory_audio_buffers.user.is_empty:
+                user_audio_temp_path = (
+                    await in_memory_audio_buffers.user.write_to_temp_file()
+                )
+            else:
+                logger.debug("User audio buffer is empty, skipping upload")
+
+            if not in_memory_audio_buffers.bot.is_empty:
+                bot_audio_temp_path = (
+                    await in_memory_audio_buffers.bot.write_to_temp_file()
+                )
+            else:
+                logger.debug("Bot audio buffer is empty, skipping upload")
+
             transcript_temp_path = in_memory_logs_buffer.write_transcript_to_temp_file()
             if not transcript_temp_path:
                 logger.debug("No transcript events in logs buffer, skipping upload")
@@ -385,16 +403,18 @@ def register_event_handlers(
             workflow_run_id,
             audio_temp_path,
             transcript_temp_path,
+            user_audio_temp_path,
+            bot_audio_temp_path,
         )
 
     # Return the buffer so it can be passed to other handlers
-    return in_memory_audio_buffer
+    return in_memory_audio_buffers
 
 
 def register_audio_data_handler(
     audio_buffer: AudioBufferProcessor,
     workflow_run_id,
-    in_memory_buffer: InMemoryAudioBuffer,
+    in_memory_buffers: InMemoryRecordingBuffers,
 ):
     """Register event handler for audio data"""
     logger.info(f"Registering audio data handler for workflow run {workflow_run_id}")
@@ -404,9 +424,19 @@ def register_audio_data_handler(
         if not audio:
             return
 
-        # Use in-memory buffer
         try:
-            await in_memory_buffer.append(audio)
+            await in_memory_buffers.mixed.append(audio)
         except MemoryError as e:
-            logger.error(f"Memory buffer full: {e}")
-            # Could implement overflow to disk here if needed
+            logger.error(f"Mixed audio buffer full: {e}")
+
+    @audio_buffer.event_handler("on_track_audio_data")
+    async def on_track_audio_data(
+        buffer, user_audio, bot_audio, sample_rate, num_channels
+    ):
+        try:
+            if user_audio:
+                await in_memory_buffers.user.append(user_audio)
+            if bot_audio:
+                await in_memory_buffers.bot.append(bot_audio)
+        except MemoryError as e:
+            logger.error(f"Track audio buffer full: {e}")

api/services/pipecat/in_memory_buffers.py

@@ -75,6 +75,27 @@ class InMemoryAudioBuffer:
         return self._total_size
 
 
+class InMemoryRecordingBuffers:
+    """Holds the mixed recording plus aligned user and bot mono tracks."""
+
+    def __init__(self, workflow_run_id: int, sample_rate: int, num_channels: int = 1):
+        self.mixed = InMemoryAudioBuffer(
+            workflow_run_id=workflow_run_id,
+            sample_rate=sample_rate,
+            num_channels=num_channels,
+        )
+        self.user = InMemoryAudioBuffer(
+            workflow_run_id=workflow_run_id,
+            sample_rate=sample_rate,
+            num_channels=1,
+        )
+        self.bot = InMemoryAudioBuffer(
+            workflow_run_id=workflow_run_id,
+            sample_rate=sample_rate,
+            num_channels=1,
+        )
+
+
 class InMemoryLogsBuffer:
     """Buffer real-time feedback events in memory during a call, then save to workflow run logs."""
 

api/services/pipecat/run_pipeline.py

@@ -6,6 +6,7 @@ from loguru import logger
 
 from api.db import db_client
 from api.enums import WorkflowRunMode
+from api.services.configuration.options import DEEPGRAM_FLUX_MODELS
 from api.services.configuration.registry import ServiceProviders
 from api.services.integrations import (
     IntegrationRuntimeContext,
@@ -162,15 +163,13 @@ async def run_pipeline_telephony(
         workflow_id: Workflow being executed.
         workflow_run_id: Workflow run row.
         user_id: Owner of the workflow.
-        call_id: Provider call identifier (stored in cost_info for billing).
+        call_id: Provider call identifier.
         transport_kwargs: Provider-specific kwargs forwarded to the transport
             factory (e.g. stream_sid + call_sid for Twilio).
     """
     logger.debug(f"Running {provider_name} pipeline for workflow_run {workflow_run_id}")
     set_current_run_id(workflow_run_id)
 
-    await db_client.update_workflow_run(workflow_run_id, cost_info={"call_id": call_id})
-
     workflow = await db_client.get_workflow(workflow_id, user_id)
     if workflow:
         set_current_org_id(workflow.organization_id)
@@ -195,14 +194,17 @@ async def run_pipeline_telephony(
     # Resolve effective user config here so the transport can tune its
     # bot-stopped-speaking fallback based on is_realtime; pass the resolved
     # values into _run_pipeline so it doesn't fetch them again.
-    from api.services.configuration.resolve import resolve_effective_config
+    from api.services.configuration.ai_model_configuration import (
+        get_effective_ai_model_configuration_for_workflow,
+    )
 
-    user_config = await db_client.get_user_configurations(user_id)
     run_configs = (
         (workflow_run.definition.workflow_configurations or {}) if workflow_run else {}
     )
-    user_config = resolve_effective_config(
-        user_config, run_configs.get("model_overrides")
+    user_config = await get_effective_ai_model_configuration_for_workflow(
+        user_id=user_id,
+        organization_id=workflow.organization_id if workflow else None,
+        workflow_configurations=run_configs,
     )
     is_realtime = bool(user_config.is_realtime and user_config.realtime is not None)
 
@@ -272,15 +274,18 @@ async def run_pipeline_smallwebrtc(
     # Resolve workflow_run + effective user_config here so the transport can
     # tune its bot-stopped-speaking fallback based on is_realtime. _run_pipeline
     # reuses these via kwargs so we don't fetch twice.
-    from api.services.configuration.resolve import resolve_effective_config
+    from api.services.configuration.ai_model_configuration import (
+        get_effective_ai_model_configuration_for_workflow,
+    )
 
     workflow_run = await db_client.get_workflow_run(workflow_run_id, user_id)
-    user_config = await db_client.get_user_configurations(user_id)
     run_configs = (
         (workflow_run.definition.workflow_configurations or {}) if workflow_run else {}
     )
-    user_config = resolve_effective_config(
-        user_config, run_configs.get("model_overrides")
+    user_config = await get_effective_ai_model_configuration_for_workflow(
+        user_id=user_id,
+        organization_id=workflow.organization_id if workflow else None,
+        workflow_configurations=run_configs,
     )
     is_realtime = bool(user_config.is_realtime and user_config.realtime is not None)
 
@@ -334,7 +339,7 @@ async def _run_pipeline(
     if workflow_run.is_completed:
         raise HTTPException(status_code=400, detail="Workflow run already completed")
 
-    merged_call_context_vars = workflow_run.initial_context
+    merged_call_context_vars = dict(workflow_run.initial_context or {})
     # If there is some extra call_context_vars, fold them in. Persistence
     # happens once below, after runtime_configuration is also resolved.
     if call_context_vars:
@@ -380,15 +385,31 @@ async def _run_pipeline(
     # Resolve model overrides from the version onto global user config (skip
     # when the caller already resolved it).
     if resolved_user_config is None:
-        from api.services.configuration.resolve import resolve_effective_config
+        from api.services.configuration.ai_model_configuration import (
+            get_effective_ai_model_configuration_for_workflow,
+        )
 
-        user_config = await db_client.get_user_configurations(user_id)
-        user_config = resolve_effective_config(
-            user_config, run_configs.get("model_overrides")
+        user_config = await get_effective_ai_model_configuration_for_workflow(
+            user_id=user_id,
+            organization_id=workflow.organization_id,
+            workflow_configurations=run_configs,
         )
     else:
         user_config = resolved_user_config
 
+    from api.services.managed_model_services import (
+        MPS_CORRELATION_ID_CONTEXT_KEY,
+        ensure_mps_correlation_id,
+    )
+
+    mps_correlation_id = await ensure_mps_correlation_id(
+        ai_model_config=user_config,
+        workflow_run_id=workflow_run_id,
+        initial_context=merged_call_context_vars,
+    )
+    if mps_correlation_id:
+        merged_call_context_vars[MPS_CORRELATION_ID_CONTEXT_KEY] = mps_correlation_id
+
     # Detect realtime mode (speech-to-speech services like OpenAI Realtime, Gemini Live)
     is_realtime = user_config.is_realtime and user_config.realtime is not None
 
@@ -400,11 +421,23 @@ async def _run_pipeline(
         # Realtime services don't implement run_inference, so create a
         # separate text LLM for variable extraction and other out-of-band
         # inference calls.
-        inference_llm = create_llm_service(user_config)
+        inference_llm = create_llm_service(
+            user_config,
+            correlation_id=mps_correlation_id,
+        )
     else:
-        stt = create_stt_service(user_config, audio_config, keyterms=keyterms)
-        tts = create_tts_service(user_config, audio_config)
-        llm = create_llm_service(user_config)
+        stt = create_stt_service(
+            user_config,
+            audio_config,
+            keyterms=keyterms,
+            correlation_id=mps_correlation_id,
+        )
+        tts = create_tts_service(
+            user_config,
+            audio_config,
+            correlation_id=mps_correlation_id,
+        )
+        llm = create_llm_service(user_config, correlation_id=mps_correlation_id)
         inference_llm = None
 
     # Stamp the providers/models actually resolved for this run onto
@@ -508,10 +541,17 @@ async def _run_pipeline(
     embeddings_endpoint = None
     embeddings_api_version = None
     if user_config and user_config.embeddings:
+        from api.services.configuration.ai_model_configuration import (
+            apply_managed_embeddings_base_url,
+        )
+
         embeddings_api_key = user_config.embeddings.api_key
         embeddings_model = user_config.embeddings.model
         embeddings_provider = getattr(user_config.embeddings, "provider", None)
-        embeddings_base_url = getattr(user_config.embeddings, "base_url", None)
+        embeddings_base_url = apply_managed_embeddings_base_url(
+            provider=embeddings_provider,
+            base_url=getattr(user_config.embeddings, "base_url", None),
+        )
         embeddings_endpoint = getattr(user_config.embeddings, "endpoint", None)
         embeddings_api_version = getattr(user_config.embeddings, "api_version", None)
 
@@ -587,7 +627,7 @@ async def _run_pipeline(
         # Other models use configurable turn detection strategy
         is_deepgram_flux = (
             user_config.stt.provider == ServiceProviders.DEEPGRAM.value
-            and user_config.stt.model == "flux-general-en"
+            and user_config.stt.model in DEEPGRAM_FLUX_MODELS
         )
 
         if is_deepgram_flux:
@@ -679,7 +719,10 @@ async def _run_pipeline(
         # Create a separate LLM instance for the voicemail sub-pipeline
         # (can't share with main pipeline as it would mess up frame linking)
         if voicemail_config.get("use_workflow_llm", True):
-            voicemail_llm = create_llm_service(user_config)
+            voicemail_llm = create_llm_service(
+                user_config,
+                correlation_id=mps_correlation_id,
+            )
         else:
             voicemail_llm = create_llm_service_from_provider(
                 provider=voicemail_config.get("provider", "openai"),

api/services/pipecat/service_factory.py

@@ -6,6 +6,7 @@ from fastapi import HTTPException
 from loguru import logger
 
 from api.constants import MPS_API_URL
+from api.services.configuration.options import DEEPGRAM_FLUX_MODELS
 from api.services.configuration.registry import ServiceProviders
 from api.services.pipecat.inworld_tts import InworldOwnedSessionTTSService
 from api.services.pipecat.minimax_tts import MiniMaxOwnedSessionTTSService
@@ -41,8 +42,17 @@ from pipecat.services.google.vertex.llm import (
 )
 from pipecat.services.inworld.tts import InworldTTSSettings
 from pipecat.services.groq.llm import GroqLLMService, GroqLLMSettings
+from pipecat.services.huggingface.llm import (
+    HuggingFaceLLMService,
+    HuggingFaceLLMSettings,
+)
+from pipecat.services.huggingface.stt import (
+    HuggingFaceSTTService,
+    HuggingFaceSTTSettings,
+)
 from pipecat.services.minimax.llm import MiniMaxLLMService
 from pipecat.services.minimax.tts import MiniMaxTTSSettings
+from pipecat.services.openai._constants import OPENAI_SAMPLE_RATE
 from pipecat.services.openai.base_llm import OpenAILLMSettings
 from pipecat.services.openai.llm import OpenAILLMService
 from pipecat.services.openai.stt import (
@@ -55,6 +65,8 @@ from pipecat.services.rime.tts import RimeTTSService, RimeTTSSettings
 from pipecat.services.sarvam.llm import SarvamLLMService, SarvamLLMSettings
 from pipecat.services.sarvam.stt import SarvamSTTService, SarvamSTTSettings
 from pipecat.services.sarvam.tts import SarvamTTSService, SarvamTTSSettings
+from pipecat.services.smallest.stt import SmallestSTTService, SmallestSTTSettings
+from pipecat.services.smallest.tts import SmallestTTSService, SmallestTTSSettings
 from pipecat.services.speaches.llm import SpeachesLLMService, SpeachesLLMSettings
 from pipecat.services.speaches.stt import SpeachesSTTService, SpeachesSTTSettings
 from pipecat.services.speaches.tts import SpeachesTTSService, SpeachesTTSSettings
@@ -69,6 +81,20 @@ if TYPE_CHECKING:
     from api.services.pipecat.audio_config import AudioConfig
 
 
+DEEPGRAM_FLUX_LANGUAGE_HINTS = {
+    "de": Language.DE,
+    "en": Language.EN,
+    "es": Language.ES,
+    "fr": Language.FR,
+    "hi": Language.HI,
+    "it": Language.IT,
+    "ja": Language.JA,
+    "nl": Language.NL,
+    "pt": Language.PT,
+    "ru": Language.RU,
+}
+
+
 def _validate_runtime_service_url(url: str, field_name: str) -> None:
     try:
         validate_user_configured_service_url(
@@ -80,7 +106,10 @@ def _validate_runtime_service_url(url: str, field_name: str) -> None:
 
 
 def create_stt_service(
-    user_config, audio_config: "AudioConfig", keyterms: list[str] | None = None
+    user_config,
+    audio_config: "AudioConfig",
+    keyterms: list[str] | None = None,
+    correlation_id: str | None = None,
 ):
     """Create and return appropriate STT service based on user configuration
 
@@ -92,17 +121,23 @@ def create_stt_service(
         f"Creating STT service: provider={user_config.stt.provider}, model={user_config.stt.model}"
     )
     if user_config.stt.provider == ServiceProviders.DEEPGRAM.value:
-        # Check if using Flux model (English-only, no language selection)
-        if user_config.stt.model == "flux-general-en":
+        if user_config.stt.model in DEEPGRAM_FLUX_MODELS:
+            settings_kwargs = {
+                "model": user_config.stt.model,
+                "eot_timeout_ms": 3000,
+                "eot_threshold": 0.7,
+                "eager_eot_threshold": 0.5,
+                "keyterm": keyterms or [],
+            }
+            if user_config.stt.model == "flux-general-multi":
+                language = getattr(user_config.stt, "language", None)
+                language_hint = DEEPGRAM_FLUX_LANGUAGE_HINTS.get(language)
+                if language_hint:
+                    settings_kwargs["language_hints"] = [language_hint]
+
             return DeepgramFluxSTTService(
                 api_key=user_config.stt.api_key,
-                settings=DeepgramFluxSTTSettings(
-                    model=user_config.stt.model,
-                    eot_timeout_ms=3000,
-                    eot_threshold=0.7,
-                    eager_eot_threshold=0.5,
-                    keyterm=keyterms or [],
-                ),
+                settings=DeepgramFluxSTTSettings(**settings_kwargs),
                 should_interrupt=False,  # Let UserAggregator take care of sending InterruptionFrame
                 sample_rate=audio_config.transport_in_sample_rate,
             )
@@ -162,6 +197,7 @@ def create_stt_service(
         return DograhSTTService(
             base_url=base_url,
             api_key=user_config.stt.api_key,
+            correlation_id=correlation_id,
             settings=DograhSTTSettings(
                 model=user_config.stt.model,
                 language=language,
@@ -216,6 +252,22 @@ def create_stt_service(
             ),
             sample_rate=audio_config.transport_in_sample_rate,
         )
+    elif user_config.stt.provider == ServiceProviders.HUGGINGFACE.value:
+        base_url = (
+            getattr(user_config.stt, "base_url", None)
+            or "https://router.huggingface.co/hf-inference"
+        )
+        _validate_runtime_service_url(base_url, "base_url")
+        return HuggingFaceSTTService(
+            api_key=user_config.stt.api_key,
+            base_url=base_url,
+            bill_to=getattr(user_config.stt, "bill_to", None),
+            settings=HuggingFaceSTTSettings(
+                model=user_config.stt.model,
+                return_timestamps=getattr(user_config.stt, "return_timestamps", False),
+            ),
+            sample_rate=audio_config.transport_in_sample_rate,
+        )
     elif user_config.stt.provider == ServiceProviders.ASSEMBLYAI.value:
         language = getattr(user_config.stt, "language", None)
         settings_kwargs = {"model": user_config.stt.model, "language": language}
@@ -282,13 +334,29 @@ def create_stt_service(
             settings=AzureSTTSettings(language=pipecat_language),
             sample_rate=audio_config.transport_in_sample_rate,
         )
+    elif user_config.stt.provider == ServiceProviders.SMALLEST.value:
+        language_code = getattr(user_config.stt, "language", None) or "en"
+        try:
+            pipecat_language = Language(language_code)
+        except ValueError:
+            pipecat_language = Language.EN
+        return SmallestSTTService(
+            api_key=user_config.stt.api_key,
+            settings=SmallestSTTSettings(
+                model=user_config.stt.model,
+                language=pipecat_language,
+            ),
+            sample_rate=audio_config.transport_in_sample_rate,
+        )
     else:
         raise HTTPException(
             status_code=400, detail=f"Invalid STT provider {user_config.stt.provider}"
         )
 
 
-def create_tts_service(user_config, audio_config: "AudioConfig"):
+def create_tts_service(
+    user_config, audio_config: "AudioConfig", correlation_id: str | None = None
+):
     """Create and return appropriate TTS service based on user configuration
 
     Args:
@@ -316,6 +384,7 @@ def create_tts_service(user_config, audio_config: "AudioConfig"):
             kwargs["base_url"] = base_url
         return OpenAITTSService(
             api_key=user_config.tts.api_key,
+            sample_rate=OPENAI_SAMPLE_RATE,
             settings=OpenAITTSSettings(model=user_config.tts.model),
             text_filters=[xml_function_tag_filter],
             skip_aggregator_types=["recording_router", "recording"],
@@ -385,11 +454,13 @@ def create_tts_service(user_config, audio_config: "AudioConfig"):
         generation_config = (
             GenerationConfig(**gen_config_kwargs) if gen_config_kwargs else None
         )
+        language = getattr(user_config.tts, "language", None) or "en"
         return CartesiaTTSService(
             api_key=user_config.tts.api_key,
             settings=CartesiaTTSSettings(
                 voice=user_config.tts.voice,
                 model=user_config.tts.model,
+                language=language,
                 **(
                     {"generation_config": generation_config}
                     if generation_config
@@ -428,6 +499,7 @@ def create_tts_service(user_config, audio_config: "AudioConfig"):
         return DograhTTSService(
             base_url=base_url,
             api_key=user_config.tts.api_key,
+            correlation_id=correlation_id,
             settings=DograhTTSSettings(
                 model=user_config.tts.model,
                 voice=user_config.tts.voice,
@@ -509,14 +581,20 @@ def create_tts_service(user_config, audio_config: "AudioConfig"):
         language = getattr(user_config.tts, "language", None)
         pipecat_language = language_mapping.get(language, Language.HI)
 
-        voice = getattr(user_config.tts, "voice", None) or "anushka"
+        voice = (
+            getattr(user_config.tts, "voice", None) or ""
+        ).strip().lower() or "anushka"
+        speed = getattr(user_config.tts, "speed", None)
+        settings_kwargs = {
+            "model": user_config.tts.model,
+            "voice": voice,
+            "language": pipecat_language,
+        }
+        if speed and speed != 1.0:
+            settings_kwargs["pace"] = speed
         return SarvamTTSService(
             api_key=user_config.tts.api_key,
-            settings=SarvamTTSSettings(
-                model=user_config.tts.model,
-                voice=voice,
-                language=pipecat_language,
-            ),
+            settings=SarvamTTSSettings(**settings_kwargs),
             text_filters=[xml_function_tag_filter],
             skip_aggregator_types=["recording_router", "recording"],
             silence_time_s=1.0,
@@ -577,6 +655,28 @@ def create_tts_service(user_config, audio_config: "AudioConfig"):
             skip_aggregator_types=["recording_router", "recording"],
             silence_time_s=1.0,
         )
+    elif user_config.tts.provider == ServiceProviders.SMALLEST.value:
+        language_code = getattr(user_config.tts, "language", None) or "en"
+        try:
+            pipecat_language = Language(language_code)
+        except ValueError:
+            pipecat_language = Language.EN
+        speed = getattr(user_config.tts, "speed", None)
+        model = user_config.tts.model.replace("lightning-v", "lightning_v")
+        settings_kwargs = SmallestTTSSettings(
+            model=model,
+            voice=user_config.tts.voice,
+            language=pipecat_language,
+        )
+        if speed and speed != 1.0:
+            settings_kwargs.speed = speed
+        return SmallestTTSService(
+            api_key=user_config.tts.api_key,
+            settings=settings_kwargs,
+            text_filters=[xml_function_tag_filter],
+            skip_aggregator_types=["recording_router", "recording"],
+            silence_time_s=1.0,
+        )
     else:
         raise HTTPException(
             status_code=400, detail=f"Invalid TTS provider {user_config.tts.provider}"
@@ -588,6 +688,7 @@ def create_llm_service_from_provider(
     model: str,
     api_key: str | None,
     *,
+    correlation_id: str | None = None,
     base_url: str | None = None,
     endpoint: str | None = None,
     aws_access_key: str | None = None,
@@ -597,6 +698,7 @@ def create_llm_service_from_provider(
     location: str | None = None,
     credentials: str | None = None,
     temperature: float | None = None,
+    bill_to: str | None = None,
 ):
     """Create an LLM service from explicit provider/model/api_key.
 
@@ -661,6 +763,7 @@ def create_llm_service_from_provider(
         return DograhLLMService(
             base_url=f"{MPS_API_URL}/api/v1/llm",
             api_key=api_key,
+            correlation_id=correlation_id,
             settings=OpenAILLMSettings(model=model),
         )
     elif provider == ServiceProviders.AWS_BEDROCK.value:
@@ -678,6 +781,15 @@ def create_llm_service_from_provider(
             api_key=api_key or "none",
             settings=SpeachesLLMSettings(model=model),
         )
+    elif provider == ServiceProviders.HUGGINGFACE.value:
+        base_url = base_url or "https://router.huggingface.co/v1"
+        _validate_runtime_service_url(base_url, "base_url")
+        return HuggingFaceLLMService(
+            api_key=api_key,
+            base_url=base_url,
+            bill_to=bill_to,
+            settings=HuggingFaceLLMSettings(model=model, temperature=0.1),
+        )
     elif provider == ServiceProviders.MINIMAX.value:
         base_url = base_url or "https://api.minimax.io/v1"
         _validate_runtime_service_url(base_url, "base_url")
@@ -875,7 +987,7 @@ def create_realtime_llm_service(user_config, audio_config: "AudioConfig"):
         )
 
 
-def create_llm_service(user_config):
+def create_llm_service(user_config, correlation_id: str | None = None):
     """Create and return appropriate LLM service based on user configuration."""
     provider = user_config.llm.provider
     model = user_config.llm.model
@@ -890,6 +1002,9 @@ def create_llm_service(user_config):
         kwargs["endpoint"] = user_config.llm.endpoint
     elif provider == ServiceProviders.SPEACHES.value:
         kwargs["base_url"] = user_config.llm.base_url
+    elif provider == ServiceProviders.HUGGINGFACE.value:
+        kwargs["base_url"] = user_config.llm.base_url
+        kwargs["bill_to"] = user_config.llm.bill_to
     elif provider == ServiceProviders.AWS_BEDROCK.value:
         kwargs["aws_access_key"] = user_config.llm.aws_access_key
         kwargs["aws_secret_key"] = user_config.llm.aws_secret_key
@@ -904,4 +1019,10 @@ def create_llm_service(user_config):
     elif provider == ServiceProviders.SARVAM.value:
         kwargs["temperature"] = user_config.llm.temperature
 
-    return create_llm_service_from_provider(provider, model, api_key, **kwargs)
+    return create_llm_service_from_provider(
+        provider,
+        model,
+        api_key,
+        correlation_id=correlation_id,
+        **kwargs,
+    )

api/services/pricing/README.md

@@ -1,76 +0,0 @@
-# Pricing Module
-
-This module contains pricing models and registries for different AI services used in workflow cost calculations.
-
-## Structure
-
-```
-pricing/
-├── __init__.py           # Main module exports
-├── models.py            # Base pricing model classes
-├── llm.py              # LLM pricing configurations
-├── tts.py              # TTS pricing configurations  
-├── stt.py              # STT pricing configurations
-├── registry.py         # Combined pricing registry
-└── README.md           # This file
-```
-
-## Pricing Models
-
-### TokenPricingModel
-Used for LLM services that charge based on tokens:
-- `prompt_token_price`: Cost per prompt token
-- `completion_token_price`: Cost per completion token
-- `cache_read_discount`: Discount for cache read tokens (default 50%)
-- `cache_creation_multiplier`: Premium for cache creation tokens (default 25%)
-
-### CharacterPricingModel
-Used for TTS services that charge based on character count:
-- `character_price`: Cost per character
-
-### TimePricingModel
-Used for STT services that charge based on time:
-- `second_price`: Cost per second
-
-## Adding New Pricing
-
-### Adding a New LLM Model
-Edit `llm.py` and add the model to the appropriate provider:
-
-```python
-ServiceProviders.OPENAI: {
-    "new-model": TokenPricingModel(
-        prompt_token_price=Decimal("2.00") / 1000000,
-        completion_token_price=Decimal("8.00") / 1000000,
-    ),
-    # ... existing models
-}
-```
-
-### Adding a New Provider
-1. Add pricing configurations to the appropriate service file (llm.py, tts.py, stt.py)
-2. The registry will automatically include them
-
-### Adding a New Service Type
-1. Create a new pricing file (e.g., `image.py`)
-2. Define the pricing models
-3. Import and add to `registry.py`
-
-## Usage
-
-The pricing registry is automatically imported and used by the cost calculator:
-
-```python
-from api.services.pricing import PRICING_REGISTRY
-from api.services.workflow.cost_calculator import cost_calculator
-
-# The cost calculator uses the pricing registry automatically
-result = cost_calculator.calculate_total_cost(usage_info)
-```
-
-## Maintenance
-
-- Update pricing when providers change their rates
-- All prices should use `Decimal` for precision
-- Include comments with current pricing from provider documentation
-- Test changes with existing test suite 

api/services/pricing/__init__.py

@@ -1,9 +0,0 @@
-"""
-Pricing module for workflow cost calculation.
-
-This module contains pricing models and registries for different AI services.
-"""
-
-from .registry import PRICING_REGISTRY
-
-__all__ = ["PRICING_REGISTRY"]

api/services/pricing/cost_calculator.py

@@ -1,228 +0,0 @@
-"""
-Cost Calculator for Workflow Runs
-
-This module provides a comprehensive cost calculation system for workflow runs based on usage metrics
-from different AI service providers (OpenAI, Groq, Deepgram, etc.).
-
-Features:
-- Token-based pricing for LLM services with cache optimization support
-- Character-based pricing for TTS services
-- Time-based pricing for STT services
-- Configurable pricing models that can be updated
-- Support for multiple providers and models
-- Automatic provider inference from model names
-- JSON serialization support for database storage
-
-Usage:
-    from api.tasks.cost_calculator import cost_calculator
-
-    usage_info = {
-        "llm": {
-            "processor_name|||gpt-4o": {
-                "prompt_tokens": 1000,
-                "completion_tokens": 500,
-                "total_tokens": 1500,
-                "cache_read_input_tokens": 0,
-                "cache_creation_input_tokens": 0
-            }
-        },
-        "tts": {
-            "processor_name|||aura-2-helena-en": 2000  # character count
-        }
-    }
-
-    cost_breakdown = cost_calculator.calculate_total_cost(usage_info)
-    print(f"Total cost: ${cost_breakdown['total']:.6f}")
-"""
-
-from decimal import Decimal
-from typing import Any, Dict, Optional, Tuple
-
-from api.services.configuration.registry import ServiceProviders
-from api.services.pricing import PRICING_REGISTRY
-from api.services.pricing.models import (
-    PricingModel,
-)
-
-
-class CostCalculator:
-    """Main cost calculator class"""
-
-    def __init__(self, pricing_registry: Dict = None):
-        self.pricing_registry = pricing_registry or PRICING_REGISTRY
-
-    def get_pricing_model(
-        self, service_type: str, provider: str, model: str
-    ) -> Optional[PricingModel]:
-        """Get pricing model for a specific service, provider, and model"""
-        try:
-            service_pricing = self.pricing_registry.get(service_type, {})
-
-            # Try to get pricing for the specific provider
-            provider_pricing = service_pricing.get(provider, {})
-            pricing_model = provider_pricing.get(model) or provider_pricing.get(
-                "default"
-            )
-
-            if pricing_model:
-                return pricing_model
-
-            # If not found, try the "default" provider for this service type
-            default_provider_pricing = service_pricing.get("default", {})
-            return default_provider_pricing.get(model) or default_provider_pricing.get(
-                "default"
-            )
-
-        except (KeyError, AttributeError):
-            return None
-
-    def calculate_llm_cost(
-        self, provider: str, model: str, usage: Dict[str, int]
-    ) -> Decimal:
-        """Calculate cost for LLM usage"""
-        pricing_model = self.get_pricing_model("llm", provider, model)
-        if not pricing_model:
-            return Decimal("0")
-        return pricing_model.calculate_cost(usage)
-
-    def calculate_tts_cost(
-        self, provider: str, model: str, character_count: int
-    ) -> Decimal:
-        """Calculate cost for TTS usage"""
-        pricing_model = self.get_pricing_model("tts", provider, model)
-        if not pricing_model:
-            return Decimal("0")
-        return pricing_model.calculate_cost(character_count)
-
-    def calculate_stt_cost(self, provider: str, model: str, seconds: float) -> Decimal:
-        """Calculate cost for STT usage"""
-        pricing_model = self.get_pricing_model("stt", provider, model)
-        if not pricing_model:
-            return Decimal("0")
-        return pricing_model.calculate_cost(seconds)
-
-    def calculate_total_cost(self, usage_info: Dict) -> Dict[str, Any]:
-        llm_cost_total = Decimal("0")
-        tts_cost_total = Decimal("0")
-        stt_cost_total = Decimal("0")
-
-        # Calculate LLM costs
-        llm_usage = usage_info.get("llm", {})
-        for key, usage in llm_usage.items():
-            processor, model = self._parse_key(key)
-            # Try to determine provider from processor name or model
-            provider = self._infer_provider_from_model(model, "llm")
-            cost = self.calculate_llm_cost(provider, model, usage)
-            llm_cost_total += cost
-
-        # Calculate TTS costs
-        tts_usage = usage_info.get("tts", {})
-        for key, character_count in tts_usage.items():
-            processor, model = self._parse_key(key)
-            # Handle the case where model is "None" - infer from processor
-            if model.lower() in ["none", "null", ""]:
-                provider = self._infer_provider_from_processor(processor, "tts")
-                model = "default"  # Use default model for the provider
-            else:
-                provider = self._infer_provider_from_model(model, "tts")
-            cost = self.calculate_tts_cost(provider, model, character_count)
-            tts_cost_total += cost
-
-        # Calculate STT costs from explicit stt usage
-        stt_usage = usage_info.get("stt", {})
-        for key, seconds in stt_usage.items():
-            processor, model = self._parse_key(key)
-            provider = self._infer_provider_from_model(model, "stt")
-            cost = self.calculate_stt_cost(provider, model, seconds)
-            stt_cost_total += cost
-
-        total_cost = llm_cost_total + tts_cost_total + stt_cost_total
-
-        return {
-            "llm_cost": float(llm_cost_total),
-            "tts_cost": float(tts_cost_total),
-            "stt_cost": float(stt_cost_total),
-            "total": float(total_cost),
-        }
-
-    def _parse_key(self, key) -> Tuple[str, str]:
-        """Parse key which is in format 'processor|||model'"""
-        if isinstance(key, str) and "|||" in key:
-            parts = key.split("|||", 1)
-            return parts[0], parts[1]
-        else:
-            # Fallback for backwards compatibility or malformed keys
-            return str(key), "unknown"
-
-    def _infer_provider_from_model(self, model: str, service_type: str) -> str:
-        """Infer provider from model name"""
-        if not model:
-            return "unknown"
-
-        model_lower = model.lower()
-
-        # OpenAI models
-        if any(keyword in model_lower for keyword in ["gpt", "whisper", "openai"]):
-            return ServiceProviders.OPENAI
-
-        # Groq models
-        if any(keyword in model_lower for keyword in ["groq"]):
-            return ServiceProviders.GROQ
-
-        # Elevenlabs models
-        if any(keyword in model_lower for keyword in ["eleven"]):
-            return ServiceProviders.ELEVENLABS
-
-        # Deepgram models
-        if any(
-            keyword in model_lower
-            for keyword in ["deepgram", "nova", "phonecall", "general"]
-        ):
-            return ServiceProviders.DEEPGRAM
-
-        # Default to first available provider for the service type
-        service_providers = self.pricing_registry.get(service_type, {})
-        if service_providers:
-            return list(service_providers.keys())[0]
-
-        return "unknown"
-
-    def _infer_provider_from_processor(self, processor: str, service_type: str) -> str:
-        """Infer provider from processor name"""
-        if not processor:
-            return "unknown"
-
-        processor_lower = processor.lower()
-
-        # OpenAI processors
-        if any(keyword in processor_lower for keyword in ["openai", "gpt"]):
-            return ServiceProviders.OPENAI
-
-        # Groq processors
-        if any(keyword in processor_lower for keyword in ["groq"]):
-            return ServiceProviders.GROQ
-
-        # Deepgram processors
-        if any(keyword in processor_lower for keyword in ["deepgram"]):
-            return ServiceProviders.DEEPGRAM
-
-        # Default to first available provider for the service type
-        service_providers = self.pricing_registry.get(service_type, {})
-        if service_providers:
-            return list(service_providers.keys())[0]
-
-        return "unknown"
-
-    def update_pricing(
-        self, service_type: str, provider: str, model: str, pricing_model: PricingModel
-    ):
-        """Update pricing for a specific service/provider/model combination"""
-        if service_type not in self.pricing_registry:
-            self.pricing_registry[service_type] = {}
-        if provider not in self.pricing_registry[service_type]:
-            self.pricing_registry[service_type][provider] = {}
-        self.pricing_registry[service_type][provider][model] = pricing_model
-
-
-# Global cost calculator instance
-cost_calculator = CostCalculator()

api/services/pricing/embeddings.py

@@ -1,44 +0,0 @@
-"""
-Embeddings pricing models for different providers.
-
-Prices are per token for embedding models.
-"""
-
-from decimal import Decimal
-from typing import Dict
-
-from api.services.configuration.registry import ServiceProviders
-
-from .models import PricingModel
-
-
-class EmbeddingPricingModel(PricingModel):
-    """Pricing model for token-based embedding services."""
-
-    def __init__(self, token_price: Decimal):
-        """Initialize with price per token.
-
-        Args:
-            token_price: Cost per token for embedding
-        """
-        self.token_price = token_price
-
-    def calculate_cost(self, token_count: int) -> Decimal:
-        """Calculate cost for embedding token usage."""
-        return Decimal(token_count) * self.token_price
-
-
-# Embeddings pricing registry
-EMBEDDINGS_PRICING: Dict[str, Dict[str, EmbeddingPricingModel]] = {
-    ServiceProviders.OPENAI: {
-        "text-embedding-3-small": EmbeddingPricingModel(
-            token_price=Decimal("0.02") / 1_000_000,  # $0.02 per 1M tokens
-        ),
-        "text-embedding-3-large": EmbeddingPricingModel(
-            token_price=Decimal("0.13") / 1_000_000,  # $0.13 per 1M tokens
-        ),
-        "text-embedding-ada-002": EmbeddingPricingModel(
-            token_price=Decimal("0.10") / 1_000_000,  # $0.10 per 1M tokens (legacy)
-        ),
-    },
-}

api/services/pricing/llm.py

@@ -1,143 +0,0 @@
-"""
-LLM pricing models for different providers.
-
-Prices are per 1000 tokens for most models, with some newer models priced per million tokens.
-"""
-
-from decimal import Decimal
-from typing import Dict
-
-from api.services.configuration.registry import ServiceProviders
-
-from .models import TokenPricingModel
-
-# LLM pricing registry
-LLM_PRICING: Dict[str, Dict[str, TokenPricingModel]] = {
-    ServiceProviders.OPENAI: {
-        "gpt-3.5-turbo": TokenPricingModel(
-            prompt_token_price=Decimal("0.0015") / 1000,  # $0.0015 per 1K tokens
-            completion_token_price=Decimal("0.002") / 1000,  # $0.002 per 1K tokens
-        ),
-        "gpt-4": TokenPricingModel(
-            prompt_token_price=Decimal("0.03") / 1000,  # $0.03 per 1K tokens
-            completion_token_price=Decimal("0.06") / 1000,  # $0.06 per 1K tokens
-        ),
-        "gpt-4.1": TokenPricingModel(
-            prompt_token_price=Decimal("2.00") / 1000000,  # $2.00 per 1M tokens
-            completion_token_price=Decimal("8.00") / 1000000,  # $8.00 per 1M tokens
-        ),
-        "gpt-4.1-mini": TokenPricingModel(
-            prompt_token_price=Decimal("0.40") / 1000000,  # $0.40 per 1M tokens
-            completion_token_price=Decimal("1.60") / 1000000,  # $1.60 per 1M tokens
-        ),
-        "gpt-4.1-nano": TokenPricingModel(
-            prompt_token_price=Decimal("0.10") / 1000000,  # $0.10 per 1M tokens
-            completion_token_price=Decimal("0.40") / 1000000,  # $0.40 per 1M tokens
-        ),
-        "gpt-4.5-preview": TokenPricingModel(
-            prompt_token_price=Decimal("75.00") / 1000000,  # $75.00 per 1M tokens
-            completion_token_price=Decimal("150.00") / 1000000,  # $150.00 per 1M tokens
-        ),
-        "gpt-4o": TokenPricingModel(
-            prompt_token_price=Decimal("2.50") / 1000000,  # $2.50 per 1M tokens - FIXED
-            completion_token_price=Decimal("10.00")
-            / 1000000,  # $10.00 per 1M tokens - FIXED
-        ),
-        "gpt-4o-audio-preview": TokenPricingModel(
-            prompt_token_price=Decimal("2.50") / 1000000,  # $2.50 per 1M tokens
-            completion_token_price=Decimal("10.00") / 1000000,  # $10.00 per 1M tokens
-        ),
-        "gpt-4o-realtime-preview": TokenPricingModel(
-            prompt_token_price=Decimal("5.00") / 1000000,  # $5.00 per 1M tokens
-            completion_token_price=Decimal("20.00") / 1000000,  # $20.00 per 1M tokens
-        ),
-        "gpt-4o-mini": TokenPricingModel(
-            prompt_token_price=Decimal("0.15") / 1000000,  # $0.15 per 1M tokens
-            completion_token_price=Decimal("0.60") / 1000000,  # $0.60 per 1M tokens
-        ),
-        "gpt-4o-mini-audio-preview": TokenPricingModel(
-            prompt_token_price=Decimal("0.15") / 1000000,  # $0.15 per 1M tokens
-            completion_token_price=Decimal("0.60") / 1000000,  # $0.60 per 1M tokens
-        ),
-        "gpt-4o-mini-realtime-preview": TokenPricingModel(
-            prompt_token_price=Decimal("0.60") / 1000000,  # $0.60 per 1M tokens
-            completion_token_price=Decimal("2.40") / 1000000,  # $2.40 per 1M tokens
-        ),
-        "gpt-4o-search-preview": TokenPricingModel(
-            prompt_token_price=Decimal("2.50") / 1000000,  # $2.50 per 1M tokens
-            completion_token_price=Decimal("10.00") / 1000000,  # $10.00 per 1M tokens
-        ),
-        "gpt-4o-mini-search-preview": TokenPricingModel(
-            prompt_token_price=Decimal("0.15") / 1000000,  # $0.15 per 1M tokens
-            completion_token_price=Decimal("0.60") / 1000000,  # $0.60 per 1M tokens
-        ),
-        "o1": TokenPricingModel(
-            prompt_token_price=Decimal("15.00") / 1000000,  # $15.00 per 1M tokens
-            completion_token_price=Decimal("60.00") / 1000000,  # $60.00 per 1M tokens
-        ),
-        "o1-pro": TokenPricingModel(
-            prompt_token_price=Decimal("150.00") / 1000000,  # $150.00 per 1M tokens
-            completion_token_price=Decimal("600.00") / 1000000,  # $600.00 per 1M tokens
-        ),
-        "o1-mini": TokenPricingModel(
-            prompt_token_price=Decimal("1.10") / 1000000,  # $1.10 per 1M tokens
-            completion_token_price=Decimal("4.40") / 1000000,  # $4.40 per 1M tokens
-        ),
-        "o3": TokenPricingModel(
-            prompt_token_price=Decimal("10.00") / 1000000,  # $10.00 per 1M tokens
-            completion_token_price=Decimal("40.00") / 1000000,  # $40.00 per 1M tokens
-        ),
-        "o3-mini": TokenPricingModel(
-            prompt_token_price=Decimal("1.10") / 1000000,  # $1.10 per 1M tokens
-            completion_token_price=Decimal("4.40") / 1000000,  # $4.40 per 1M tokens
-        ),
-        "o4-mini": TokenPricingModel(
-            prompt_token_price=Decimal("1.10") / 1000000,  # $1.10 per 1M tokens
-            completion_token_price=Decimal("4.40") / 1000000,  # $4.40 per 1M tokens
-        ),
-        "computer-use-preview": TokenPricingModel(
-            prompt_token_price=Decimal("3.00") / 1000000,  # $3.00 per 1M tokens
-            completion_token_price=Decimal("12.00") / 1000000,  # $12.00 per 1M tokens
-        ),
-        "gpt-image-1": TokenPricingModel(
-            prompt_token_price=Decimal("5.00") / 1000000,  # $5.00 per 1M tokens
-            completion_token_price=Decimal("0") / 1000000,  # No output pricing shown
-        ),
-        "codex-mini-latest": TokenPricingModel(
-            prompt_token_price=Decimal("1.50") / 1000000,  # $1.50 per 1M tokens
-            completion_token_price=Decimal("6.00") / 1000000,  # $6.00 per 1M tokens
-        ),
-        # Transcription models
-        "gpt-4o-transcribe": TokenPricingModel(
-            prompt_token_price=Decimal("2.50") / 1000000,  # $2.50 per 1M tokens
-            completion_token_price=Decimal("10.00") / 1000000,  # $10.00 per 1M tokens
-        ),
-        "gpt-4o-mini-transcribe": TokenPricingModel(
-            prompt_token_price=Decimal("1.25") / 1000000,  # $1.25 per 1M tokens
-            completion_token_price=Decimal("5.00") / 1000000,  # $5.00 per 1M tokens
-        ),
-        # TTS models with token-based pricing
-        "gpt-4o-mini-tts": TokenPricingModel(
-            prompt_token_price=Decimal("0.60") / 1000000,  # $0.60 per 1M tokens
-            completion_token_price=Decimal("0")
-            / 1000000,  # No completion tokens for TTS
-        ),
-    },
-    ServiceProviders.GROQ: {
-        "llama-3.3-70b-versatile": TokenPricingModel(
-            prompt_token_price=Decimal("0.00059") / 1000,  # $0.00059 per 1K tokens
-            completion_token_price=Decimal("0.00079") / 1000,  # $0.00079 per 1K tokens
-        ),
-        "deepseek-r1-distill-llama-70b": TokenPricingModel(
-            prompt_token_price=Decimal("0.00059") / 1000,  # Assuming similar pricing
-            completion_token_price=Decimal("0.00079") / 1000,
-        ),
-    },
-    ServiceProviders.AZURE: {
-        "gpt-4.1-mini": TokenPricingModel(
-            prompt_token_price=Decimal("0.44") / 1000000,  # $0.40 per 1M tokens
-            completion_token_price=Decimal("8.80")
-            / 1000000,  # $1.60 per 1M tokens if using data zone
-        )
-    },
-}

api/services/pricing/models.py

@@ -1,89 +0,0 @@
-"""
-Base pricing models for different service types.
-"""
-
-from decimal import Decimal
-from enum import Enum
-from typing import Any, Dict
-
-
-class CostType(Enum):
-    LLM_TOKENS = "llm_tokens"
-    TTS_CHARACTERS = "tts_characters"
-    STT_SECONDS = "stt_seconds"
-
-
-class PricingModel:
-    """Base class for pricing models"""
-
-    def calculate_cost(self, usage: Any) -> Decimal:
-        """Calculate cost based on usage"""
-        raise NotImplementedError
-
-
-class TokenPricingModel(PricingModel):
-    """Pricing model for token-based services (LLM)"""
-
-    def __init__(
-        self,
-        prompt_token_price: Decimal,
-        completion_token_price: Decimal,
-        cache_read_discount: Decimal = Decimal("0.5"),  # 50% discount for cache reads
-        cache_creation_multiplier: Decimal = Decimal(
-            "1.25"
-        ),  # 25% premium for cache creation
-    ):
-        self.prompt_token_price = prompt_token_price
-        self.completion_token_price = completion_token_price
-        self.cache_read_discount = cache_read_discount
-        self.cache_creation_multiplier = cache_creation_multiplier
-
-    def calculate_cost(self, usage: Dict[str, int]) -> Decimal:
-        """Calculate cost for LLM token usage"""
-        prompt_tokens = usage.get("prompt_tokens", 0)
-        completion_tokens = usage.get("completion_tokens", 0)
-        cache_read_tokens = usage.get("cache_read_input_tokens") or 0
-        cache_creation_tokens = usage.get("cache_creation_input_tokens") or 0
-
-        # Base cost
-        prompt_cost = Decimal(prompt_tokens) * self.prompt_token_price
-        completion_cost = Decimal(completion_tokens) * self.completion_token_price
-
-        # Cache adjustments
-        cache_read_savings = (
-            Decimal(cache_read_tokens)
-            * self.prompt_token_price
-            * self.cache_read_discount
-        )
-        cache_creation_premium = (
-            Decimal(cache_creation_tokens)
-            * self.prompt_token_price
-            * (self.cache_creation_multiplier - 1)
-        )
-
-        total_cost = (
-            prompt_cost + completion_cost - cache_read_savings + cache_creation_premium
-        )
-        return max(total_cost, Decimal("0"))  # Ensure non-negative
-
-
-class CharacterPricingModel(PricingModel):
-    """Pricing model for character-based services (TTS)"""
-
-    def __init__(self, character_price: Decimal):
-        self.character_price = character_price
-
-    def calculate_cost(self, character_count: int) -> Decimal:
-        """Calculate cost for TTS character usage"""
-        return Decimal(character_count) * self.character_price
-
-
-class TimePricingModel(PricingModel):
-    """Pricing model for time-based services (STT)"""
-
-    def __init__(self, second_price: Decimal):
-        self.second_price = second_price
-
-    def calculate_cost(self, seconds: float) -> Decimal:
-        """Calculate cost for STT time usage"""
-        return Decimal(str(seconds)) * self.second_price

api/services/pricing/registry.py

@@ -1,18 +0,0 @@
-"""
-Main pricing registry that combines all service type pricing models.
-"""
-
-from typing import Dict
-
-from .embeddings import EMBEDDINGS_PRICING
-from .llm import LLM_PRICING
-from .stt import STT_PRICING
-from .tts import TTS_PRICING
-
-# Combined pricing registry for all service types
-PRICING_REGISTRY: Dict = {
-    "llm": LLM_PRICING,
-    "tts": TTS_PRICING,
-    "stt": STT_PRICING,
-    "embeddings": EMBEDDINGS_PRICING,
-}

api/services/pricing/run_usage_response.py

@@ -1,13 +0,0 @@
-"""Format workflow run usage for public API responses."""
-
-
-def format_public_usage_info(usage_info: dict | None) -> dict | None:
-    if not usage_info:
-        return None
-
-    return {
-        "llm": usage_info.get("llm") or {},
-        "tts": usage_info.get("tts") or {},
-        "stt": usage_info.get("stt") or {},
-        "call_duration_seconds": usage_info.get("call_duration_seconds"),
-    }

api/services/pricing/stt.py

@@ -1,26 +0,0 @@
-"""
-STT (Speech-to-Text) pricing models for different providers.
-
-Prices are per second for STT services.
-"""
-
-from decimal import Decimal
-from typing import Dict
-
-from api.services.configuration.registry import ServiceProviders
-
-from .models import TimePricingModel
-
-# STT pricing registry
-STT_PRICING: Dict[str, Dict[str, TimePricingModel]] = {
-    ServiceProviders.DEEPGRAM: {
-        "nova-3-general": TimePricingModel(Decimal("0.0077") / 60),
-        "nova-2": TimePricingModel(Decimal("0.0058") / 60),
-        "default": TimePricingModel(Decimal("0.0077") / 60),
-    },
-    ServiceProviders.OPENAI: {
-        "gpt-4o-transcribe": TimePricingModel(Decimal("0.015") / 60),
-        "default": TimePricingModel(Decimal("0.015") / 60),
-    },
-    "default": {"default": TimePricingModel(Decimal("0.0077") / 60)},
-}

api/services/pricing/tts.py

@@ -1,30 +0,0 @@
-"""
-TTS (Text-to-Speech) pricing models for different providers.
-
-Prices are per character for TTS services.
-"""
-
-from decimal import Decimal
-from typing import Dict
-
-from api.services.configuration.registry import ServiceProviders
-
-from .models import CharacterPricingModel
-
-# TTS pricing registry
-TTS_PRICING: Dict[str, Dict[str, CharacterPricingModel]] = {
-    ServiceProviders.OPENAI: {
-        "gpt-4o-mini-tts": CharacterPricingModel(Decimal("0.6") / 1_00_00_000),
-        "default": CharacterPricingModel(Decimal("0.6") / 1_00_00_000),
-    },
-    ServiceProviders.DEEPGRAM: {
-        "aura-2": CharacterPricingModel(Decimal("0.030") / 1_000),
-        "aura-1": CharacterPricingModel(Decimal("0.015") / 1_000),
-        "default": CharacterPricingModel(Decimal("0.030") / 1_000),
-    },
-    ServiceProviders.ELEVENLABS: {
-        # 6400 usd per 250*1e6 characters
-        "default": CharacterPricingModel(Decimal("0.0256") / 1_000)
-    },
-    "default": {"default": CharacterPricingModel(Decimal("0.030") / 1_000)},
-}

api/services/pricing/workflow_run_cost.py

@@ -1,230 +0,0 @@
-from decimal import Decimal
-
-from loguru import logger
-
-from api.db import db_client
-from api.enums import WorkflowRunMode
-from api.services.pricing.cost_calculator import cost_calculator
-from api.services.telephony.factory import get_telephony_provider_for_run
-
-
-async def _fetch_telephony_cost(workflow_run) -> dict | None:
-    """Fetch telephony call cost. Returns a dict with cost_usd and provider_name, or None."""
-    if (
-        workflow_run.mode
-        not in [WorkflowRunMode.TWILIO.value, WorkflowRunMode.VONAGE.value]
-        or not workflow_run.cost_info
-    ):
-        return None
-
-    call_id = workflow_run.cost_info.get("call_id")
-    if not call_id:
-        logger.warning(f"call_id not found in cost_info")
-        return None
-
-    provider_name = workflow_run.mode.lower() if workflow_run.mode else ""
-
-    workflow = await db_client.get_workflow_by_id(workflow_run.workflow_id)
-    if not workflow:
-        logger.warning("Workflow not found for workflow run")
-        raise Exception("Workflow not found")
-
-    provider = await get_telephony_provider_for_run(
-        workflow_run, workflow.organization_id
-    )
-    call_cost_info = await provider.get_call_cost(call_id)
-
-    if call_cost_info.get("status") == "error":
-        logger.error(
-            f"Failed to fetch {provider_name} call cost: {call_cost_info.get('error')}"
-        )
-        return None
-
-    cost_usd = call_cost_info.get("cost_usd", 0.0)
-    logger.info(
-        f"{provider_name.title()} call cost: ${cost_usd:.6f} USD for call {call_id}"
-    )
-    return {"cost_usd": cost_usd, "provider_name": provider_name}
-
-
-async def _update_organization_usage(
-    org, dograh_tokens: float, duration_seconds: float, charge_usd: float | None
-) -> None:
-    """Update organization usage after a workflow run."""
-    org_id = org.id
-    await db_client.update_usage_after_run(
-        org_id, dograh_tokens, duration_seconds, charge_usd
-    )
-    if charge_usd is not None:
-        logger.info(
-            f"Updated organization usage with ${charge_usd:.2f} USD ({dograh_tokens} Dograh Tokens) and {duration_seconds}s duration for org {org_id}"
-        )
-    else:
-        logger.info(
-            f"Updated organization usage with {dograh_tokens} Dograh Tokens and {duration_seconds}s duration for org {org_id}"
-        )
-
-
-async def _get_pricing_organization(workflow_run):
-    workflow = getattr(workflow_run, "workflow", None)
-    organization_id = getattr(workflow, "organization_id", None)
-    if organization_id is None and workflow and workflow.user:
-        organization_id = workflow.user.selected_organization_id
-    if organization_id is None:
-        return None
-    return await db_client.get_organization_by_id(organization_id)
-
-
-async def _build_usage_cost_snapshot(
-    usage_info: dict | None,
-    *,
-    workflow_run=None,
-    include_telephony_cost: bool = False,
-    organization=None,
-    calculated_at: str | None = None,
-) -> dict | None:
-    if not usage_info:
-        logger.warning("No usage info available for workflow run")
-        return None
-
-    cost_breakdown = cost_calculator.calculate_total_cost(usage_info)
-
-    if include_telephony_cost and workflow_run is not None:
-        try:
-            telephony_cost = await _fetch_telephony_cost(workflow_run)
-            if telephony_cost:
-                telephony_cost_usd = telephony_cost["cost_usd"]
-                provider_name = telephony_cost["provider_name"]
-                cost_breakdown["telephony_call"] = telephony_cost_usd
-                cost_breakdown[f"{provider_name}_call"] = telephony_cost_usd
-                cost_breakdown["total"] = (
-                    float(cost_breakdown["total"]) + telephony_cost_usd
-                )
-        except Exception as e:
-            logger.error(f"Failed to fetch telephony call cost: {e}")
-            # Don't fail the whole cost calculation if telephony API fails
-
-    total_cost_usd = Decimal(str(cost_breakdown["total"]))
-    dograh_tokens = float(total_cost_usd * Decimal("100"))
-
-    if organization is None and workflow_run is not None:
-        organization = await _get_pricing_organization(workflow_run)
-
-    charge_usd = None
-    if organization and organization.price_per_second_usd:
-        duration_seconds = usage_info.get("call_duration_seconds", 0)
-        charge_usd = float(
-            Decimal(str(duration_seconds))
-            * Decimal(str(organization.price_per_second_usd))
-        )
-
-    cost_info = {
-        "cost_breakdown": cost_breakdown,
-        "total_cost_usd": float(total_cost_usd),
-        "dograh_token_usage": dograh_tokens,
-        "calculated_at": calculated_at
-        or (workflow_run.created_at.isoformat() if workflow_run is not None else None),
-        "call_duration_seconds": usage_info.get("call_duration_seconds", 0),
-    }
-
-    if charge_usd is not None:
-        cost_info["charge_usd"] = charge_usd
-        cost_info["price_per_second_usd"] = organization.price_per_second_usd
-
-    return cost_info
-
-
-async def build_workflow_run_cost_info(workflow_run) -> dict | None:
-    cost_info = await _build_usage_cost_snapshot(
-        workflow_run.usage_info,
-        workflow_run=workflow_run,
-        include_telephony_cost=True,
-        calculated_at=workflow_run.created_at.isoformat(),
-    )
-    if cost_info is None:
-        return None
-    return {
-        **(workflow_run.cost_info or {}),
-        **cost_info,
-    }
-
-
-async def save_workflow_run_cost_info(
-    workflow_run_id: int, cost_info: dict | None
-) -> None:
-    if cost_info is None:
-        return
-    await db_client.update_workflow_run(run_id=workflow_run_id, cost_info=cost_info)
-
-
-async def apply_workflow_run_usage_to_organization(
-    workflow_run, cost_info: dict | None
-) -> None:
-    if cost_info is None:
-        return
-
-    org = await _get_pricing_organization(workflow_run)
-    if not org:
-        return
-
-    await _update_organization_usage(
-        org,
-        float(cost_info.get("dograh_token_usage") or 0),
-        float(cost_info.get("call_duration_seconds") or 0),
-        cost_info.get("charge_usd"),
-    )
-
-
-async def apply_usage_delta_to_organization(
-    workflow_run, usage_info: dict | None
-) -> dict | None:
-    org = await _get_pricing_organization(workflow_run)
-    if not org:
-        return None
-
-    cost_info = await _build_usage_cost_snapshot(usage_info, organization=org)
-    if cost_info is None:
-        return None
-
-    await _update_organization_usage(
-        org,
-        float(cost_info.get("dograh_token_usage") or 0),
-        float(cost_info.get("call_duration_seconds") or 0),
-        cost_info.get("charge_usd"),
-    )
-    return cost_info
-
-
-async def calculate_workflow_run_cost(workflow_run_id: int):
-    logger.debug("Calculating cost for workflow run")
-
-    workflow_run = await db_client.get_workflow_run_by_id(workflow_run_id)
-    if not workflow_run:
-        logger.warning("Workflow run not found")
-        return
-
-    try:
-        cost_info = await build_workflow_run_cost_info(workflow_run)
-        if cost_info is None:
-            return
-
-        await save_workflow_run_cost_info(workflow_run_id, cost_info)
-
-        try:
-            await apply_workflow_run_usage_to_organization(workflow_run, cost_info)
-        except Exception as e:
-            org = await _get_pricing_organization(workflow_run)
-            if org:
-                logger.error(
-                    f"Failed to update organization usage for org {org.id}: {e}"
-                )
-            else:
-                logger.error(f"Failed to update organization usage: {e}")
-            # Don't fail the whole cost calculation if usage update fails
-
-        logger.info(
-            f"Calculated cost for workflow run: ${cost_info['total_cost_usd']:.6f} USD ({cost_info['dograh_token_usage']} Dograh Tokens)"
-        )
-    except Exception as e:
-        logger.error(f"Error calculating cost for workflow run: {e}")
-        raise

api/services/quota_service.py

@@ -5,15 +5,38 @@ across different endpoints (WebRTC signaling, telephony, public API triggers).
 """
 
 from dataclasses import dataclass
+from typing import Any
 
 from loguru import logger
 
+from api.constants import DEPLOYMENT_MODE
 from api.db import db_client
 from api.db.models import UserModel
+from api.services.configuration.ai_model_configuration import (
+    get_effective_ai_model_configuration_for_workflow,
+)
 from api.services.configuration.registry import ServiceProviders
-from api.services.configuration.resolve import resolve_effective_config
+from api.services.managed_model_services import (
+    MPS_CORRELATION_ID_CONTEXT_KEY,
+    get_dograh_service_api_key,
+    uses_managed_model_services_v2,
+)
 from api.services.mps_service_key_client import mps_service_key_client
 
+MINIMUM_DOGRAH_CREDITS_FOR_CALL = 0.10
+
+LEGACY_QUOTA_EXCEEDED_MESSAGE = (
+    "You have exhausted your trial credits. "
+    "Please email founders@dograh.com for additional Dograh credits "
+    "or change providers in Models configurations."
+)
+
+BILLING_V2_QUOTA_EXCEEDED_MESSAGE = (
+    "You have exhausted your Dograh credits. "
+    "Please purchase more credits from /billing "
+    "or change providers in Models configurations."
+)
+
 
 @dataclass
 class QuotaCheckResult:
@@ -24,104 +47,359 @@ class QuotaCheckResult:
     error_code: str = ""
 
 
-async def check_dograh_quota(
-    user: UserModel, workflow_id: int | None = None
-) -> QuotaCheckResult:
-    """Check if user has sufficient Dograh quota for making a call.
-
-    This function checks if the user is using any Dograh services (LLM, STT, TTS)
-    and validates that they have sufficient credits remaining.
-
-    When ``workflow_id`` is provided, the workflow's per-workflow
-    ``model_overrides`` are merged onto the user's global config so the quota
-    check runs against the credentials that will actually be used for the call
-    (rather than always falling back to the user's defaults).
-
-    Args:
-        user: The user to check quota for
-        workflow_id: Optional workflow whose ``model_overrides`` should be
-            applied when resolving the effective service config.
-
-    Returns:
-        QuotaCheckResult with has_quota=True if user has sufficient quota or
-        is not using Dograh services, or has_quota=False with error_message
-        if quota is insufficient.
-    """
+def _safe_float(value: Any, default: float = 0.0) -> float:
     try:
-        # Get user configurations
-        user_config = await db_client.get_user_configurations(user.id)
+        return float(value)
+    except (TypeError, ValueError):
+        return default
 
-        if workflow_id is not None:
-            workflow = await db_client.get_workflow_by_id(workflow_id)
-            if workflow:
-                model_overrides = (workflow.workflow_configurations or {}).get(
-                    "model_overrides"
+
+def _insufficient_billing_v2_quota_result() -> QuotaCheckResult:
+    return QuotaCheckResult(
+        has_quota=False,
+        error_code="insufficient_credits",
+        error_message=BILLING_V2_QUOTA_EXCEEDED_MESSAGE,
+    )
+
+
+def _insufficient_legacy_quota_result() -> QuotaCheckResult:
+    return QuotaCheckResult(
+        has_quota=False,
+        error_code="quota_exceeded",
+        error_message=LEGACY_QUOTA_EXCEEDED_MESSAGE,
+    )
+
+
+def _service_uses_dograh(service: Any) -> bool:
+    provider = getattr(service, "provider", None)
+    return (
+        provider == ServiceProviders.DOGRAH or provider == ServiceProviders.DOGRAH.value
+    )
+
+
+def _dograh_api_keys(user_config: Any) -> set[str]:
+    api_keys: set[str] = set()
+    for section_name in ("llm", "stt", "tts", "embeddings"):
+        service = getattr(user_config, section_name, None)
+        if not _service_uses_dograh(service):
+            continue
+        if hasattr(service, "get_all_api_keys"):
+            all_api_keys = [
+                api_key
+                for api_key in service.get_all_api_keys()
+                if isinstance(api_key, str) and api_key
+            ]
+            if all_api_keys:
+                api_keys.update(all_api_keys)
+                continue
+        api_key = getattr(service, "api_key", None)
+        if api_key:
+            api_keys.add(api_key)
+    return api_keys
+
+
+async def _store_run_correlation_id(
+    workflow_run_id: int | None,
+    correlation_id: str | None,
+) -> None:
+    if not workflow_run_id or not correlation_id:
+        return
+
+    workflow_run = await db_client.get_workflow_run_by_id(workflow_run_id)
+    if not workflow_run:
+        logger.warning(
+            "Could not store MPS correlation id for missing workflow run {}",
+            workflow_run_id,
+        )
+        return
+
+    initial_context = dict(workflow_run.initial_context or {})
+    if initial_context.get(MPS_CORRELATION_ID_CONTEXT_KEY) == correlation_id:
+        return
+
+    initial_context[MPS_CORRELATION_ID_CONTEXT_KEY] = correlation_id
+    await db_client.update_workflow_run(
+        workflow_run_id,
+        initial_context=initial_context,
+    )
+
+
+async def _authorize_hosted_workflow_run_start(
+    *,
+    workflow_owner: UserModel,
+    organization_id: int | None,
+    workflow_id: int | None,
+    workflow_run_id: int | None,
+    user_config: Any,
+) -> tuple[QuotaCheckResult, bool]:
+    """Authorize hosted v2 billing and return whether MPS handled enforcement."""
+    if DEPLOYMENT_MODE == "oss" or organization_id is None:
+        return QuotaCheckResult(has_quota=True), False
+
+    requires_correlation = bool(
+        workflow_run_id and uses_managed_model_services_v2(user_config)
+    )
+    service_key = (
+        get_dograh_service_api_key(user_config) if requires_correlation else None
+    )
+    if requires_correlation and not service_key:
+        return (
+            QuotaCheckResult(
+                has_quota=False,
+                error_code="invalid_service_key",
+                error_message=(
+                    "You have invalid keys in your model configuration. "
+                    "Please validate the service keys."
+                ),
+            ),
+            True,
+        )
+
+    try:
+        authorization = await mps_service_key_client.authorize_workflow_run_start(
+            organization_id=organization_id,
+            workflow_run_id=workflow_run_id,
+            service_key=service_key,
+            require_correlation_id=requires_correlation,
+            minimum_credits=MINIMUM_DOGRAH_CREDITS_FOR_CALL,
+            created_by=(
+                str(workflow_owner.provider_id)
+                if workflow_owner.provider_id is not None
+                else None
+            ),
+            metadata={
+                "dograh_user_id": str(workflow_owner.id),
+                "workflow_id": workflow_id,
+            },
+        )
+    except Exception as e:
+        logger.error(
+            "Failed to authorize workflow start with MPS for org {}: {}",
+            organization_id,
+            e,
+        )
+        return (
+            QuotaCheckResult(
+                has_quota=False,
+                error_code="quota_check_failed",
+                error_message="Could not verify Dograh credits. Please try again.",
+            ),
+            True,
+        )
+
+    billing_mode = authorization.get("billing_mode")
+    if billing_mode != "v2":
+        return QuotaCheckResult(has_quota=True), False
+
+    remaining = _safe_float(authorization.get("remaining_credits"))
+    if (
+        not authorization.get("allowed", False)
+        or remaining < MINIMUM_DOGRAH_CREDITS_FOR_CALL
+    ):
+        logger.warning(
+            "Insufficient Dograh billing v2 credits for org {}: {:.2f} credits remaining",
+            organization_id,
+            remaining,
+        )
+        return _insufficient_billing_v2_quota_result(), True
+
+    try:
+        await _store_run_correlation_id(
+            workflow_run_id,
+            authorization.get("correlation_id"),
+        )
+    except Exception as e:
+        logger.error(
+            "Failed to store MPS correlation id for workflow_run_id {}: {}",
+            workflow_run_id,
+            e,
+        )
+        return (
+            QuotaCheckResult(
+                has_quota=False,
+                error_code="quota_check_failed",
+                error_message="Could not verify Dograh credits. Please try again.",
+            ),
+            True,
+        )
+    logger.info(
+        "Dograh billing v2 run authorization passed for org {}: {:.2f} credits remaining",
+        organization_id,
+        remaining,
+    )
+    return QuotaCheckResult(has_quota=True), True
+
+
+async def _authorize_legacy_dograh_keys(
+    *,
+    dograh_api_keys: set[str],
+    organization_id: int | None,
+    workflow_owner: UserModel,
+) -> QuotaCheckResult:
+    for api_key in dograh_api_keys:
+        try:
+            usage = await mps_service_key_client.check_service_key_usage(
+                api_key,
+                organization_id=organization_id,
+                created_by=workflow_owner.provider_id,
+            )
+            remaining = usage.get("remaining_credits", 0.0)
+
+            # Require at least $0.10 for a short call
+            if remaining < MINIMUM_DOGRAH_CREDITS_FOR_CALL:
+                logger.warning(
+                    f"Insufficient Dograh credits for key ...{api_key[-8:]}: "
+                    f"${remaining:.2f} remaining"
                 )
-                if model_overrides:
-                    user_config = resolve_effective_config(user_config, model_overrides)
+                return _insufficient_legacy_quota_result()
 
-        # Check if user is using any Dograh service
-        using_dograh = False
-        dograh_api_keys = set()
-
-        if user_config.llm and user_config.llm.provider == ServiceProviders.DOGRAH:
-            using_dograh = True
-            dograh_api_keys.add(user_config.llm.api_key)
-
-        if user_config.stt and user_config.stt.provider == ServiceProviders.DOGRAH:
-            using_dograh = True
-            dograh_api_keys.add(user_config.stt.api_key)
-
-        if user_config.tts and user_config.tts.provider == ServiceProviders.DOGRAH:
-            using_dograh = True
-            dograh_api_keys.add(user_config.tts.api_key)
-
-        # If not using Dograh, quota check passes
-        if not using_dograh:
-            return QuotaCheckResult(has_quota=True)
-
-        # Check quota for ALL Dograh keys
-        for api_key in dograh_api_keys:
-            try:
-                usage = await mps_service_key_client.check_service_key_usage(
-                    api_key, created_by=user.provider_id
-                )
-                remaining = usage.get("remaining_credits", 0.0)
-
-                # Require at least $0.10 for a short call
-                if remaining < 0.10:
-                    logger.warning(
-                        f"Insufficient Dograh credits for key ...{api_key[-8:]}: "
-                        f"${remaining:.2f} remaining"
-                    )
-                    return QuotaCheckResult(
-                        has_quota=False,
-                        error_code="quota_exceeded",
-                        error_message=(
-                            "You have exhausted your trial credits. "
-                            "Please email founders@dograh.com for additional Dograh credits "
-                            "or change providers in Models configurations."
-                        ),
-                    )
-
-                logger.info(
-                    f"Dograh quota check passed for key ...{api_key[-8:]}: "
-                    f"{remaining:.2f} credits remaining"
-                )
-            except Exception as e:
-                logger.error(f"Failed to check quota for Dograh key: {str(e)}")
-                error_str = str(e)
-                if "404" in error_str or "not found" in error_str.lower():
-                    return QuotaCheckResult(
-                        has_quota=False,
-                        error_code="invalid_service_key",
-                        error_message="You have invalid keys in your model configuration. Please validate the service keys.",
-                    )
+            logger.info(
+                f"Dograh quota check passed for key ...{api_key[-8:]}: "
+                f"{remaining:.2f} credits remaining"
+            )
+        except Exception as e:
+            logger.error(f"Failed to check quota for Dograh key: {str(e)}")
+            error_str = str(e)
+            if "404" in error_str or "not found" in error_str.lower():
                 return QuotaCheckResult(
                     has_quota=False,
-                    error_code="quota_check_failed",
-                    error_message="Could not verify Dograh credits. Please try again.",
+                    error_code="invalid_service_key",
+                    error_message="You have invalid keys in your model configuration. Please validate the service keys.",
                 )
+            return QuotaCheckResult(
+                has_quota=False,
+                error_code="quota_check_failed",
+                error_message="Could not verify Dograh credits. Please try again.",
+            )
+
+    return QuotaCheckResult(has_quota=True)
+
+
+async def _authorize_oss_managed_v2_correlation(
+    *,
+    workflow_id: int,
+    workflow_run_id: int | None,
+    user_config: Any,
+) -> QuotaCheckResult:
+    if not workflow_run_id or not uses_managed_model_services_v2(user_config):
+        return QuotaCheckResult(has_quota=True)
+
+    service_key = get_dograh_service_api_key(user_config)
+    if not service_key:
+        return QuotaCheckResult(
+            has_quota=False,
+            error_code="invalid_service_key",
+            error_message=(
+                "You have invalid keys in your model configuration. "
+                "Please validate the service keys."
+            ),
+        )
+
+    try:
+        response = await mps_service_key_client.create_correlation_id(
+            service_key=service_key,
+            workflow_run_id=workflow_run_id,
+        )
+        await _store_run_correlation_id(
+            workflow_run_id,
+            response.get("correlation_id"),
+        )
+    except Exception as e:
+        logger.error(
+            "Failed to authorize OSS managed v2 workflow start for workflow {} run {}: {}",
+            workflow_id,
+            workflow_run_id,
+            e,
+        )
+        return QuotaCheckResult(
+            has_quota=False,
+            error_code="quota_check_failed",
+            error_message="Could not verify Dograh credits. Please try again.",
+        )
+
+    return QuotaCheckResult(has_quota=True)
+
+
+async def authorize_workflow_run_start(
+    *,
+    workflow_id: int,
+    workflow_run_id: int | None = None,
+    actor_user: UserModel | None = None,
+) -> QuotaCheckResult:
+    """Authorize a workflow run before any billable call/text runtime starts.
+
+    The workflow organization is the billing subject for hosted v2. The workflow
+    owner is used only to resolve the effective model configuration and legacy
+    service-key metadata.
+    """
+    try:
+        workflow = await db_client.get_workflow_by_id(workflow_id)
+        if not workflow:
+            return QuotaCheckResult(
+                has_quota=False,
+                error_code="workflow_not_found",
+                error_message="Workflow not found",
+            )
+
+        actor_org_id = getattr(actor_user, "selected_organization_id", None)
+        if actor_org_id is not None and actor_org_id != workflow.organization_id:
+            logger.warning(
+                "Workflow start authorization denied: actor org {} does not match workflow {} org {}",
+                actor_org_id,
+                workflow_id,
+                workflow.organization_id,
+            )
+            return QuotaCheckResult(
+                has_quota=False,
+                error_code="workflow_not_found",
+                error_message="Workflow not found",
+            )
+
+        workflow_owner = await db_client.get_user_by_id(workflow.user_id)
+        if not workflow_owner:
+            return QuotaCheckResult(
+                has_quota=False,
+                error_code="user_not_found",
+                error_message="User not found",
+            )
+
+        user_config = await get_effective_ai_model_configuration_for_workflow(
+            user_id=workflow_owner.id,
+            organization_id=workflow.organization_id,
+            workflow_configurations=workflow.workflow_configurations,
+        )
+
+        if DEPLOYMENT_MODE != "oss":
+            hosted_result, hosted_enforced = await _authorize_hosted_workflow_run_start(
+                workflow_owner=workflow_owner,
+                organization_id=workflow.organization_id,
+                workflow_id=workflow.id,
+                workflow_run_id=workflow_run_id,
+                user_config=user_config,
+            )
+            if hosted_enforced or not hosted_result.has_quota:
+                return hosted_result
+
+        dograh_api_keys = _dograh_api_keys(user_config)
+        if not dograh_api_keys:
+            return QuotaCheckResult(has_quota=True)
+
+        legacy_result = await _authorize_legacy_dograh_keys(
+            dograh_api_keys=dograh_api_keys,
+            organization_id=(
+                None if DEPLOYMENT_MODE == "oss" else workflow.organization_id
+            ),
+            workflow_owner=workflow_owner,
+        )
+        if not legacy_result.has_quota:
+            return legacy_result
+
+        if DEPLOYMENT_MODE == "oss":
+            return await _authorize_oss_managed_v2_correlation(
+                workflow_id=workflow.id,
+                workflow_run_id=workflow_run_id,
+                user_config=user_config,
+            )
 
         return QuotaCheckResult(has_quota=True)
 
@@ -129,30 +407,3 @@ async def check_dograh_quota(
         logger.error(f"Error during quota check: {str(e)}")
         # On unexpected error, allow the call to proceed
         return QuotaCheckResult(has_quota=True)
-
-
-async def check_dograh_quota_by_user_id(
-    user_id: int, workflow_id: int | None = None
-) -> QuotaCheckResult:
-    """Check Dograh quota by user ID.
-
-    Convenience function that fetches the user and then checks quota. When
-    ``workflow_id`` is provided, the workflow's ``model_overrides`` are
-    applied so the quota check evaluates the credentials that will actually
-    be used for the call.
-
-    Args:
-        user_id: The ID of the user to check quota for
-        workflow_id: Optional workflow whose per-workflow overrides should
-            be applied to the user's config before checking quota.
-
-    Returns:
-        QuotaCheckResult with quota status
-    """
-    user = await db_client.get_user_by_id(user_id)
-    if not user:
-        return QuotaCheckResult(
-            has_quota=False,
-            error_message="User not found",
-        )
-    return await check_dograh_quota(user, workflow_id=workflow_id)

api/services/reports/run_report.py

@@ -53,7 +53,7 @@ def build_run_report_csv(runs: List[Any]) -> io.StringIO:
     for run in runs:
         initial = run.initial_context or {}
         gathered = run.gathered_context or {}
-        cost = run.cost_info or {}
+        usage = run.usage_info or {}
 
         call_tags = gathered.get("call_tags", [])
         if isinstance(call_tags, list):
@@ -67,7 +67,7 @@ def build_run_report_csv(runs: List[Any]) -> io.StringIO:
             run.created_at.isoformat() if run.created_at else "",
             initial.get("phone_number", ""),
             gathered.get("mapped_call_disposition", ""),
-            cost.get("call_duration_seconds", ""),
+            usage.get("call_duration_seconds", ""),
         ]
 
         extracted = gathered.get("extracted_variables", {})

api/services/telephony/ari_manager.py

@@ -26,7 +26,7 @@ from loguru import logger
 from api.constants import REDIS_URL
 from api.db import db_client
 from api.enums import CallType, WorkflowRunMode
-from api.services.quota_service import check_dograh_quota_by_user_id
+from api.services.quota_service import authorize_workflow_run_start
 from api.services.telephony.call_transfer_manager import get_call_transfer_manager
 from api.services.telephony.transfer_event_protocol import (
     TransferEvent,
@@ -564,19 +564,7 @@ class ARIConnection:
 
             user_id = workflow.user_id
 
-            # 3. Check quota (apply per-workflow model_overrides).
-            quota_result = await check_dograh_quota_by_user_id(
-                user_id, workflow_id=inbound_workflow_id
-            )
-            if not quota_result.has_quota:
-                logger.warning(
-                    f"[ARI org={self.organization_id}] Quota exceeded for user {user_id} "
-                    f"— hanging up inbound call {channel_id}"
-                )
-                await self._delete_channel(channel_id)
-                return
-
-            # 4. Create workflow run
+            # 3. Create workflow run
             call_id = channel_id
             workflow_run = await db_client.create_workflow_run(
                 name=f"ARI Inbound {caller_number}",
@@ -602,6 +590,20 @@ class ARIConnection:
                 f"(caller={caller_number}, called={called_number})"
             )
 
+            # 4. Check quota after the run exists so hosted v2 can mint and
+            # store the MPS correlation id before the pipeline starts.
+            quota_result = await authorize_workflow_run_start(
+                workflow_id=inbound_workflow_id,
+                workflow_run_id=workflow_run.id,
+            )
+            if not quota_result.has_quota:
+                logger.warning(
+                    f"[ARI org={self.organization_id}] Quota exceeded for user {user_id} "
+                    f"— hanging up inbound call {channel_id}"
+                )
+                await self._delete_channel(channel_id)
+                return
+
             # 5. Answer the inbound channel
             await self._answer_channel(channel_id)
 

api/services/telephony/providers/cloudonix/routes.py

@@ -103,7 +103,8 @@ async def handle_cloudonix_cdr(request: Request):
         return {"status": "error", "message": "Missing domain field"}
 
     # Extract call_id to find workflow run
-    call_id = cdr_data.get("session").get("token")
+    session = cdr_data.get("session")
+    call_id = session.get("token") if isinstance(session, dict) else None
     logger.info(f"Cloudonix CDR data for call id {call_id} - {cdr_data}")
     if not call_id:
         logger.warning("Cloudonix CDR missing call_id field")

api/services/telephony/providers/vonage/routes.py

@@ -66,34 +66,6 @@ async def handle_vonage_events(
         logger.error(f"[run {workflow_run_id}] Workflow run not found")
         return {"status": "error", "message": "Workflow run not found"}
 
-    # For a completed call that includes cost info, capture it immediately
-    if event_data.get("status") == "completed":
-        # Vonage sometimes includes price info in the webhook
-        if "price" in event_data or "rate" in event_data:
-            try:
-                if workflow_run.cost_info:
-                    # Store immediate cost info if available
-                    cost_info = workflow_run.cost_info.copy()
-                    if "price" in event_data:
-                        cost_info["vonage_webhook_price"] = float(event_data["price"])
-                    if "rate" in event_data:
-                        cost_info["vonage_webhook_rate"] = float(event_data["rate"])
-                    if "duration" in event_data:
-                        cost_info["vonage_webhook_duration"] = int(
-                            event_data["duration"]
-                        )
-
-                    await db_client.update_workflow_run(
-                        run_id=workflow_run_id, cost_info=cost_info
-                    )
-                    logger.info(
-                        f"[run {workflow_run_id}] Captured Vonage cost info from webhook"
-                    )
-            except Exception as e:
-                logger.error(
-                    f"[run {workflow_run_id}] Failed to capture Vonage cost from webhook: {e}"
-                )
-
     # Get workflow and provider
     workflow = await db_client.get_workflow_by_id(workflow_run.workflow_id)
     if not workflow:

api/services/telephony/status_processor.py

@@ -114,11 +114,13 @@ class StatusCallbackRequest(BaseModel):
             "NOANSWER": "no-answer",
         }
 
-        disposition = data.get("disposition", "")
+        disposition = data.get("disposition") or ""
         status = disposition_map.get(disposition.upper(), disposition.lower())
+        session = data.get("session")
+        call_id = session.get("token") if isinstance(session, dict) else ""
 
         return cls(
-            call_id=data.get("session").get("token"),
+            call_id=call_id or "",
             status=status,
             from_number=data.get("from"),
             to_number=data.get("to"),

api/services/user_onboarding.py

@@ -0,0 +1,37 @@
+from loguru import logger
+from pydantic import ValidationError
+
+from api.db import db_client
+from api.enums import UserConfigurationKey
+from api.schemas.onboarding_state import OnboardingState, OnboardingStateUpdate
+
+
+async def get_onboarding_state(user_id: int) -> OnboardingState:
+    value = await db_client.get_user_configuration_value(
+        user_id, UserConfigurationKey.ONBOARDING.value
+    )
+    return _parse_state(value, user_id)
+
+
+async def update_onboarding_state(
+    user_id: int, update: OnboardingStateUpdate
+) -> OnboardingState:
+    state = update.apply_to(await get_onboarding_state(user_id))
+    await db_client.upsert_user_configuration_value(
+        user_id,
+        UserConfigurationKey.ONBOARDING.value,
+        state.model_dump(mode="json", exclude_none=True),
+    )
+    return state
+
+
+def _parse_state(value, user_id: int) -> OnboardingState:
+    if not value or not isinstance(value, dict):
+        return OnboardingState()
+    try:
+        return OnboardingState.model_validate(value)
+    except ValidationError as exc:
+        logger.warning(
+            f"Invalid onboarding state for user {user_id}: {exc}. Returning defaults."
+        )
+        return OnboardingState()

api/services/workflow/dto.py

@@ -718,6 +718,8 @@ class TriggerNodeData(BaseNodeData):
                 "rsvp": "{{gathered_context.rsvp}}",
                 "duration": "{{cost_info.call_duration_seconds}}",
                 "recording_url": "{{recording_url}}",
+                "user_recording_url": "{{user_recording_url}}",
+                "bot_recording_url": "{{bot_recording_url}}",
                 "transcript_url": "{{transcript_url}}",
             },
         },

api/services/workflow/pipecat_engine.py

@@ -35,6 +35,7 @@ import asyncio
 
 from loguru import logger
 
+from api.services.managed_model_services import MPS_CORRELATION_ID_CONTEXT_KEY
 from api.services.workflow import pipecat_engine_callbacks as engine_callbacks
 from api.services.workflow.mcp_tool_session import McpToolSession
 from api.services.workflow.pipecat_engine_context_composer import (
@@ -382,6 +383,9 @@ class PipecatEngine:
                     embeddings_provider=self._embeddings_provider,
                     embeddings_endpoint=self._embeddings_endpoint,
                     embeddings_api_version=self._embeddings_api_version,
+                    correlation_id=self._call_context_vars.get(
+                        MPS_CORRELATION_ID_CONTEXT_KEY
+                    ),
                     tracing_context=self._get_otel_context(),
                 )
 

api/services/workflow/qa/llm_config.py

@@ -2,7 +2,6 @@
 
 import random
 
-from api.db import db_client
 from api.db.models import WorkflowRunModel
 from api.services.workflow.dto import QANodeData
 
@@ -43,7 +42,7 @@ async def resolve_llm_config(
 async def resolve_user_llm_config(
     workflow_run: WorkflowRunModel,
 ) -> tuple[str, str, str, dict]:
-    """Resolve the user's configured LLM (from UserConfiguration).
+    """Resolve the user's configured LLM (from EffectiveAIModelConfiguration).
 
     Returns:
         (provider, model, api_key, service_kwargs) tuple
@@ -54,7 +53,27 @@ async def resolve_user_llm_config(
 
     llm_config: dict = {}
     if user_id:
-        user_configuration = await db_client.get_user_configurations(user_id)
+        from api.services.configuration.ai_model_configuration import (
+            get_effective_ai_model_configuration_for_workflow,
+        )
+
+        workflow_configurations = {}
+        if workflow_run.definition:
+            workflow_configurations = (
+                workflow_run.definition.workflow_configurations or {}
+            )
+        elif workflow_run.workflow:
+            workflow_configurations = (
+                workflow_run.workflow.workflow_configurations or {}
+            )
+
+        user_configuration = await get_effective_ai_model_configuration_for_workflow(
+            user_id=user_id,
+            organization_id=workflow_run.workflow.organization_id
+            if workflow_run.workflow
+            else None,
+            workflow_configurations=workflow_configurations,
+        )
         llm_config = user_configuration.model_dump(exclude_none=True).get("llm", {})
 
     provider = llm_config.get("provider", "openai")

api/services/workflow/run_usage_response.py

@@ -0,0 +1,41 @@
+"""Format workflow run usage for public API responses."""
+
+
+def format_public_usage_info(usage_info: dict | None) -> dict | None:
+    if not usage_info:
+        return None
+
+    return {
+        "llm": usage_info.get("llm") or {},
+        "tts": usage_info.get("tts") or {},
+        "stt": usage_info.get("stt") or {},
+        "call_duration_seconds": usage_info.get("call_duration_seconds"),
+    }
+
+
+def format_public_cost_info(
+    cost_info: dict | None, usage_info: dict | None
+) -> dict | None:
+    """Return the legacy response shape without doing local cost accounting."""
+    duration = None
+    if usage_info and usage_info.get("call_duration_seconds") is not None:
+        duration = int(round(usage_info.get("call_duration_seconds") or 0))
+    elif cost_info and cost_info.get("call_duration_seconds") is not None:
+        duration = int(round(cost_info.get("call_duration_seconds") or 0))
+
+    dograh_token_usage = 0
+    if cost_info:
+        if "dograh_token_usage" in cost_info:
+            dograh_token_usage = cost_info.get("dograh_token_usage") or 0
+        elif "total_cost_usd" in cost_info:
+            dograh_token_usage = round(
+                float(cost_info.get("total_cost_usd", 0)) * 100, 2
+            )
+
+    if duration is None and dograh_token_usage == 0:
+        return None
+
+    return {
+        "dograh_token_usage": dograh_token_usage,
+        "call_duration_seconds": duration,
+    }

api/services/workflow/text_chat_runner.py

@@ -17,7 +17,6 @@ from pipecat.frames.frames import (
     LLMContextFrame,
     LLMFullResponseEndFrame,
     LLMFullResponseStartFrame,
-    TextFrame,
     TTSSpeakFrame,
     TTSStoppedFrame,
 )
@@ -32,7 +31,6 @@ from pipecat.utils.run_context import set_current_org_id
 
 from api.db import db_client
 from api.enums import WorkflowRunMode, WorkflowRunState
-from api.services.configuration.resolve import resolve_effective_config
 from api.services.pipecat.audio_config import create_audio_config
 from api.services.pipecat.pipeline_builder import create_pipeline_task
 from api.services.pipecat.pipeline_metrics_aggregator import (
@@ -168,12 +166,17 @@ class _TaskQueueProxy:
 
 
 class _TextChatCaptureProcessor(FrameProcessor):
-    def __init__(self, response_window: _ResponseWindowState) -> None:
+    def __init__(
+        self,
+        response_window: _ResponseWindowState,
+        context: LLMContext,
+    ) -> None:
         super().__init__()
         self.last_activity_at = time.monotonic()
         self.activity_count = 0
         self.events: list[dict[str, Any]] = []
         self._response_window = response_window
+        self._context = context
 
     def _touch(self) -> None:
         self.last_activity_at = time.monotonic()
@@ -193,12 +196,14 @@ class _TextChatCaptureProcessor(FrameProcessor):
         self._touch()
 
         if isinstance(frame, TTSSpeakFrame):
-            text_frame = TextFrame(frame.text)
-            text_frame.append_to_context = (
+            append_to_context = (
                 frame.append_to_context if frame.append_to_context is not None else True
             )
-            await self.push_frame(text_frame, direction)
-            await self.push_frame(LLMAssistantPushAggregationFrame(), direction)
+            text = frame.text.strip()
+            if text:
+                self._response_window.outputs.append(text)
+                if append_to_context:
+                    self._context.add_message({"role": "assistant", "content": text})
             return
 
         if isinstance(frame, LLMContextFrame) and direction == FrameDirection.UPSTREAM:
@@ -410,14 +415,31 @@ async def execute_text_chat_pending_turn(
     run_definition = workflow_run.definition
     run_configs = run_definition.workflow_configurations or {}
 
-    user_config = await db_client.get_user_configurations(workflow_run.workflow.user.id)
-    user_config = resolve_effective_config(
-        user_config, run_configs.get("model_overrides")
+    from api.services.configuration.ai_model_configuration import (
+        get_effective_ai_model_configuration_for_workflow,
+    )
+
+    user_config = await get_effective_ai_model_configuration_for_workflow(
+        user_id=workflow_run.workflow.user.id,
+        organization_id=workflow.organization_id,
+        workflow_configurations=run_configs,
     )
     if user_config.llm is None:
         raise ValueError("Text chat requires an LLM configuration")
 
-    llm = create_llm_service(user_config)
+    from api.services.managed_model_services import (
+        MPS_CORRELATION_ID_CONTEXT_KEY,
+        ensure_mps_correlation_id,
+    )
+
+    base_initial_context = dict(workflow_run.initial_context or {})
+    mps_correlation_id = await ensure_mps_correlation_id(
+        ai_model_config=user_config,
+        workflow_run_id=workflow_run_id,
+        initial_context=base_initial_context,
+    )
+
+    llm = create_llm_service(user_config, correlation_id=mps_correlation_id)
     inference_llm = llm
 
     runtime_configuration = {
@@ -425,19 +447,25 @@ async def execute_text_chat_pending_turn(
         "llm_model": user_config.llm.model,
     }
     initial_context = {
-        **(workflow_run.initial_context or {}),
+        **base_initial_context,
         "runtime_configuration": runtime_configuration,
     }
+    if mps_correlation_id:
+        initial_context[MPS_CORRELATION_ID_CONTEXT_KEY] = mps_correlation_id
+    await db_client.update_workflow_run(
+        workflow_run_id,
+        initial_context=initial_context,
+    )
 
     workflow_graph = WorkflowGraph(
         ReactFlowDTO.model_validate(run_definition.workflow_json)
     )
     base_checkpoint = _resolve_checkpoint_for_pending_turn(session_data, checkpoint)
 
-    response_window = _ResponseWindowState()
-    capture_processor = _TextChatCaptureProcessor(response_window)
     context = LLMContext()
     context.set_messages(base_checkpoint["messages"])
+    response_window = _ResponseWindowState()
+    capture_processor = _TextChatCaptureProcessor(response_window, context)
 
     node_transition_events = capture_processor.events
 
@@ -466,9 +494,17 @@ async def execute_text_chat_pending_turn(
     embeddings_model = None
     embeddings_base_url = None
     if user_config.embeddings:
+        from api.services.configuration.ai_model_configuration import (
+            apply_managed_embeddings_base_url,
+        )
+
         embeddings_api_key = user_config.embeddings.api_key
         embeddings_model = user_config.embeddings.model
-        embeddings_base_url = getattr(user_config.embeddings, "base_url", None)
+        embeddings_provider = getattr(user_config.embeddings, "provider", None)
+        embeddings_base_url = apply_managed_embeddings_base_url(
+            provider=embeddings_provider,
+            base_url=getattr(user_config.embeddings, "base_url", None),
+        )
 
     has_recordings = await db_client.has_active_recordings(workflow.organization_id)
     context_compaction_enabled = (workflow.workflow_configurations or {}).get(
@@ -606,8 +642,10 @@ async def execute_text_chat_pending_turn(
                 "Transportless text chat pipeline failed while closing run {}",
                 workflow_run_id,
             )
+            await engine.close_mcp_sessions()
             await engine.cleanup()
             raise
+        await engine.close_mcp_sessions()
         await engine.cleanup()
 
     gathered_context = await engine.get_gathered_context()

api/services/workflow/text_chat_session_service.py

@@ -4,17 +4,11 @@ from datetime import UTC, datetime
 from typing import Any
 from uuid import uuid4
 
-from loguru import logger
-
 from api.db import db_client
 from api.db.models import WorkflowRunTextSessionModel
 from api.db.workflow_run_text_session_client import (
     WorkflowRunTextSessionRevisionConflictError,
 )
-from api.services.pricing.workflow_run_cost import (
-    apply_usage_delta_to_organization,
-    build_workflow_run_cost_info,
-)
 from api.services.workflow.text_chat_logs import (
     build_text_chat_realtime_feedback_events,
 )
@@ -261,20 +255,6 @@ async def execute_pending_text_chat_turn(
         state=execution.state,
         is_completed=execution.is_completed,
     )
-    workflow_run = await db_client.get_workflow_run_by_id(run_id)
-    if workflow_run:
-        try:
-            # Apply the per-turn delta so org usage tracks cumulative run cost
-            # without replaying the full session totals on every turn.
-            await apply_usage_delta_to_organization(workflow_run, execution.usage)
-        except Exception as e:
-            logger.error(
-                f"Failed to update organization usage for text chat run {run_id}: {e}"
-            )
-
-        cost_info = await build_workflow_run_cost_info(workflow_run)
-        if cost_info is not None:
-            await db_client.update_workflow_run(run_id, cost_info=cost_info)
 
     return await _reload_text_chat_session(run_id)
 

api/services/workflow/tools/knowledge_base.py

@@ -29,6 +29,7 @@ async def retrieve_from_knowledge_base(
     embeddings_provider: Optional[str] = None,
     embeddings_endpoint: Optional[str] = None,
     embeddings_api_version: Optional[str] = None,
+    correlation_id: Optional[str] = None,
     tracing_context=None,
 ) -> Dict[str, Any]:
     """Retrieve relevant information from the knowledge base using vector similarity search.
@@ -75,6 +76,7 @@ async def retrieve_from_knowledge_base(
                 embeddings_provider,
                 embeddings_endpoint,
                 embeddings_api_version,
+                correlation_id,
             )
 
         # Create span with parent context
@@ -115,6 +117,7 @@ async def retrieve_from_knowledge_base(
                         embeddings_provider,
                         embeddings_endpoint,
                         embeddings_api_version,
+                        correlation_id,
                     )
 
                     # Add result metadata to span
@@ -192,6 +195,7 @@ async def retrieve_from_knowledge_base(
                 embeddings_provider,
                 embeddings_endpoint,
                 embeddings_api_version,
+                correlation_id,
             )
     else:
         # Tracing is disabled - perform retrieval without tracing
@@ -206,6 +210,7 @@ async def retrieve_from_knowledge_base(
             embeddings_provider,
             embeddings_endpoint,
             embeddings_api_version,
+            correlation_id,
         )
 
 
@@ -220,6 +225,7 @@ async def _perform_retrieval(
     embeddings_provider: Optional[str] = None,
     embeddings_endpoint: Optional[str] = None,
     embeddings_api_version: Optional[str] = None,
+    correlation_id: Optional[str] = None,
 ) -> Dict[str, Any]:
     """Internal function to perform the actual retrieval operation.
 
@@ -272,11 +278,20 @@ async def _perform_retrieval(
                     api_version=embeddings_api_version or "2024-02-15-preview",
                 )
             else:
+                default_headers = None
+                if (
+                    embeddings_provider == ServiceProviders.DOGRAH.value
+                    and correlation_id
+                ):
+                    default_headers = {
+                        "X-Dograh-Correlation-Id": correlation_id,
+                    }
                 embedding_service = OpenAIEmbeddingService(
                     db_client=db_client,
                     api_key=embeddings_api_key,
                     model_id=embeddings_model or "text-embedding-3-small",
                     base_url=embeddings_base_url,
+                    default_headers=default_headers,
                 )
 
             results = await embedding_service.search_similar_chunks(

api/services/workflow_run_billing.py

@@ -0,0 +1,134 @@
+"""Workflow-run billing hooks.
+
+Dograh does not rate or deduct credits locally. MPS owns credit accounting.
+For hosted deployments, Dograh reports completed platform usage to MPS.
+When a server-minted MPS correlation id exists, MPS uses model-service usage
+as the canonical duration. Otherwise Dograh reports the completed run duration.
+"""
+
+from typing import Any
+
+from loguru import logger
+
+from api.constants import DEPLOYMENT_MODE
+from api.db import db_client
+from api.services.managed_model_services import get_mps_correlation_id
+from api.services.mps_service_key_client import mps_service_key_client
+
+
+def _workflow_run_organization_id(workflow_run) -> int | None:
+    workflow = getattr(workflow_run, "workflow", None)
+    return getattr(workflow, "organization_id", None)
+
+
+def _duration_seconds_from_usage_info(workflow_run) -> float | None:
+    usage_info: dict[str, Any] = getattr(workflow_run, "usage_info", None) or {}
+    duration = usage_info.get("call_duration_seconds")
+    try:
+        duration_seconds = float(duration)
+    except (TypeError, ValueError):
+        return None
+
+    return duration_seconds if duration_seconds > 0 else None
+
+
+async def _organization_uses_mps_billing_v2(organization_id: int) -> bool:
+    account = await mps_service_key_client.get_billing_account_status(
+        organization_id=organization_id
+    )
+    return bool(account and account.get("billing_mode") == "v2")
+
+
+def _is_usage_not_ready_error(exc: Exception) -> bool:
+    response = getattr(exc, "response", None)
+    if getattr(response, "status_code", None) != 409:
+        return False
+    return "usage_not_ready" in (getattr(response, "text", "") or "")
+
+
+async def report_workflow_run_platform_usage(workflow_run) -> None:
+    """Report hosted platform usage for a completed workflow run to MPS."""
+    if DEPLOYMENT_MODE == "oss":
+        return
+
+    if not getattr(workflow_run, "is_completed", False):
+        logger.warning(
+            "Workflow run is not completed in report_workflow_run_platform_usage"
+        )
+        return
+
+    organization_id = _workflow_run_organization_id(workflow_run)
+    if organization_id is None:
+        logger.warning(
+            "Skipping platform usage report for workflow run {}: no organization_id",
+            workflow_run.id,
+        )
+        return
+
+    correlation_id = get_mps_correlation_id(
+        getattr(workflow_run, "initial_context", None)
+    )
+    duration_seconds = (
+        None if correlation_id else _duration_seconds_from_usage_info(workflow_run)
+    )
+    if not correlation_id and duration_seconds is None:
+        logger.warning(
+            "Skipping platform usage report for workflow run {}: no billable duration",
+            workflow_run.id,
+        )
+        return
+
+    try:
+        if not await _organization_uses_mps_billing_v2(organization_id):
+            logger.debug(
+                "Not reporting platform usage since org not using mps billing v2"
+            )
+            return
+
+        result = await mps_service_key_client.report_platform_usage(
+            organization_id=organization_id,
+            correlation_id=correlation_id,
+            duration_seconds=duration_seconds,
+            workflow_run_id=workflow_run.id,
+            metadata={
+                "source": "workflow_run_completion",
+                "workflow_id": getattr(workflow_run, "workflow_id", None),
+                "duration_source": (
+                    "mps_correlation" if correlation_id else "dograh_usage_info"
+                ),
+            },
+        )
+        logger.info(
+            "Reported platform usage for workflow run {} to MPS: {}",
+            workflow_run.id,
+            result,
+        )
+    except Exception as e:
+        if _is_usage_not_ready_error(e):
+            # A run can start and receive an MPS correlation id, then fail or end
+            # before billable STT usage is recorded. MPS returns usage_not_ready
+            # for that no-platform-fee path, so keep it out of error alerts.
+            logger.warning(
+                "Failed to report platform usage for workflow run {}: {}",
+                workflow_run.id,
+                e,
+            )
+        else:
+            logger.error(
+                "Failed to report platform usage for workflow run {}: {}",
+                workflow_run.id,
+                e,
+            )
+
+
+async def report_completed_workflow_run_platform_usage(workflow_run_id: int) -> None:
+    """Load a completed workflow run and report platform usage to MPS."""
+    workflow_run = await db_client.get_workflow_run_by_id(workflow_run_id)
+    if not workflow_run:
+        logger.warning(
+            "Skipping platform usage report: workflow run {} not found",
+            workflow_run_id,
+        )
+        return
+
+    await report_workflow_run_platform_usage(workflow_run)

api/tasks/arq.py

@@ -45,10 +45,8 @@ from api.tasks.campaign_tasks import (
 )
 from api.tasks.knowledge_base_processing import process_knowledge_base_document
 from api.tasks.run_integrations import run_integrations_post_workflow_run
-from api.tasks.s3_upload import (
-    process_workflow_completion,
-    upload_voicemail_audio_to_s3,
-)
+from api.tasks.s3_upload import upload_voicemail_audio_to_s3
+from api.tasks.workflow_completion import process_workflow_completion
 
 
 class WorkerSettings:

api/tasks/knowledge_base_processing.py

@@ -157,15 +157,31 @@ async def process_knowledge_base_document(
         embeddings_endpoint = None
         embeddings_api_version = None
         if document.created_by:
-            user_config = await db_client.get_user_configurations(document.created_by)
-            if user_config.embeddings:
-                embeddings_provider = getattr(user_config.embeddings, "provider", None)
-                embeddings_api_key = user_config.embeddings.api_key
-                embeddings_model = user_config.embeddings.model
-                embeddings_base_url = getattr(user_config.embeddings, "base_url", None)
-                embeddings_endpoint = getattr(user_config.embeddings, "endpoint", None)
+            from api.services.configuration.ai_model_configuration import (
+                apply_managed_embeddings_base_url,
+                get_resolved_ai_model_configuration,
+            )
+
+            resolved_config = await get_resolved_ai_model_configuration(
+                user_id=document.created_by,
+                organization_id=document.organization_id,
+            )
+            effective_config = resolved_config.effective
+            if effective_config.embeddings:
+                embeddings_provider = getattr(
+                    effective_config.embeddings, "provider", None
+                )
+                embeddings_api_key = effective_config.embeddings.api_key
+                embeddings_model = effective_config.embeddings.model
+                embeddings_base_url = apply_managed_embeddings_base_url(
+                    provider=embeddings_provider,
+                    base_url=getattr(effective_config.embeddings, "base_url", None),
+                )
+                embeddings_endpoint = getattr(
+                    effective_config.embeddings, "endpoint", None
+                )
                 embeddings_api_version = getattr(
-                    user_config.embeddings, "api_version", None
+                    effective_config.embeddings, "api_version", None
                 )
                 logger.info(
                     f"Using user embeddings config: provider={embeddings_provider}, "

api/tasks/run_integrations.py

@@ -27,6 +27,7 @@ from api.services.workflow.dto import (
 )
 from api.services.workflow.qa import run_per_node_qa_analysis
 from api.utils.credential_auth import build_auth_header
+from api.utils.recording_artifacts import get_recording_storage_key
 from api.utils.template_renderer import render_template
 
 
@@ -339,6 +340,10 @@ def _build_render_context(
     Returns:
         Dict containing all fields available for template rendering
     """
+    extra = workflow_run.extra or {}
+    user_recording_key = get_recording_storage_key(extra, "user")
+    bot_recording_key = get_recording_storage_key(extra, "bot")
+
     context = {
         # Top-level fields
         "workflow_run_id": workflow_run.id,
@@ -353,6 +358,7 @@ def _build_render_context(
         "cost_info": workflow_run.usage_info or {},
         # Annotations (includes QA results)
         "annotations": workflow_run.annotations or {},
+        "extra": extra,
     }
 
     # Add public download URLs if token is available
@@ -366,9 +372,17 @@ def _build_render_context(
         context["transcript_url"] = (
             f"{base_url}/transcript" if workflow_run.transcript_url else None
         )
+        context["user_recording_url"] = (
+            f"{base_url}/user_recording" if user_recording_key else None
+        )
+        context["bot_recording_url"] = (
+            f"{base_url}/bot_recording" if bot_recording_key else None
+        )
     else:
         context["recording_url"] = workflow_run.recording_url
         context["transcript_url"] = workflow_run.transcript_url
+        context["user_recording_url"] = user_recording_key
+        context["bot_recording_url"] = bot_recording_key
 
     return context
 

api/tasks/s3_upload.py

@@ -1,13 +1,9 @@
 import os
-from typing import Optional
 
 from loguru import logger
 from pipecat.utils.run_context import set_current_run_id
 
-from api.db import db_client
-from api.services.pricing.workflow_run_cost import calculate_workflow_run_cost
-from api.services.storage import get_current_storage_backend, storage_fs
-from api.tasks.run_integrations import run_integrations_post_workflow_run
+from api.services.storage import storage_fs
 
 
 async def upload_voicemail_audio_to_s3(
@@ -69,110 +65,3 @@ async def upload_voicemail_audio_to_s3(
                 logger.warning(
                     f"Failed to clean up temp voicemail audio file {temp_file_path}: {e}"
                 )
-
-
-async def process_workflow_completion(
-    _ctx,
-    workflow_run_id: int,
-    audio_temp_path: Optional[str] = None,
-    transcript_temp_path: Optional[str] = None,
-):
-    """Process workflow completion: upload artifacts and run integrations.
-
-    This task combines audio upload, transcript upload, and webhook integrations
-    into a single sequential task to ensure integrations run after uploads complete.
-
-    Args:
-        _ctx: ARQ context (unused)
-        workflow_run_id: The workflow run ID
-        audio_temp_path: Optional path to temp audio file
-        transcript_temp_path: Optional path to temp transcript file
-    """
-    run_id = str(workflow_run_id)
-    set_current_run_id(run_id)
-
-    logger.info(f"Processing workflow completion for run {workflow_run_id}")
-
-    storage_backend = get_current_storage_backend()
-
-    # Step 1: Upload audio if provided
-    if audio_temp_path:
-        try:
-            if os.path.exists(audio_temp_path):
-                file_size = os.path.getsize(audio_temp_path)
-                logger.debug(f"Audio file size: {file_size} bytes")
-
-                recording_url = f"recordings/{workflow_run_id}.wav"
-                logger.info(
-                    f"Uploading audio to {storage_backend.name} - workflow_run_id: {workflow_run_id}"
-                )
-
-                await storage_fs.aupload_file(audio_temp_path, recording_url)
-                await db_client.update_workflow_run(
-                    run_id=workflow_run_id,
-                    recording_url=recording_url,
-                    storage_backend=storage_backend.value,
-                )
-                logger.info(f"Successfully uploaded audio: {recording_url}")
-            else:
-                logger.warning(f"Audio temp file not found: {audio_temp_path}")
-        except Exception as e:
-            logger.error(f"Error uploading audio for workflow {workflow_run_id}: {e}")
-        finally:
-            if audio_temp_path and os.path.exists(audio_temp_path):
-                try:
-                    os.remove(audio_temp_path)
-                    logger.debug(f"Cleaned up temp audio file: {audio_temp_path}")
-                except Exception as e:
-                    logger.warning(f"Failed to clean up temp audio file: {e}")
-
-    # Step 2: Upload transcript if provided
-    if transcript_temp_path:
-        try:
-            if os.path.exists(transcript_temp_path):
-                file_size = os.path.getsize(transcript_temp_path)
-                logger.debug(f"Transcript file size: {file_size} bytes")
-
-                transcript_url = f"transcripts/{workflow_run_id}.txt"
-                logger.info(
-                    f"Uploading transcript to {storage_backend.name} - workflow_run_id: {workflow_run_id}"
-                )
-
-                await storage_fs.aupload_file(transcript_temp_path, transcript_url)
-                await db_client.update_workflow_run(
-                    run_id=workflow_run_id,
-                    transcript_url=transcript_url,
-                    storage_backend=storage_backend.value,
-                )
-                logger.info(f"Successfully uploaded transcript: {transcript_url}")
-            else:
-                logger.warning(
-                    f"Transcript temp file not found: {transcript_temp_path}"
-                )
-        except Exception as e:
-            logger.error(
-                f"Error uploading transcript for workflow {workflow_run_id}: {e}"
-            )
-        finally:
-            if transcript_temp_path and os.path.exists(transcript_temp_path):
-                try:
-                    os.remove(transcript_temp_path)
-                    logger.debug(
-                        f"Cleaned up temp transcript file: {transcript_temp_path}"
-                    )
-                except Exception as e:
-                    logger.warning(f"Failed to clean up temp transcript file: {e}")
-
-    # Step 3: Run integrations including QA analysis (after uploads are complete)
-    try:
-        await run_integrations_post_workflow_run(_ctx, workflow_run_id)
-    except Exception as e:
-        logger.error(f"Error running integrations for workflow {workflow_run_id}: {e}")
-
-    # Step 4: Calculate cost after integrations (so QA token usage is included)
-    try:
-        await calculate_workflow_run_cost(workflow_run_id)
-    except Exception as e:
-        logger.error(f"Error calculating cost for workflow {workflow_run_id}: {e}")
-
-    logger.info(f"Completed workflow completion processing for run {workflow_run_id}")

api/tasks/workflow_completion.py

@@ -0,0 +1,183 @@
+import os
+from typing import Optional
+
+from loguru import logger
+from pipecat.utils.run_context import set_current_run_id
+
+from api.db import db_client
+from api.services.storage import get_current_storage_backend, storage_fs
+from api.services.workflow_run_billing import (
+    report_completed_workflow_run_platform_usage,
+)
+from api.tasks.run_integrations import run_integrations_post_workflow_run
+
+
+def _recording_metadata(storage_key: str, storage_backend: str, track: str) -> dict:
+    return {
+        "storage_key": storage_key,
+        "storage_backend": storage_backend,
+        "format": "wav",
+        "track": track,
+    }
+
+
+async def _upload_temp_file(
+    workflow_run_id: int,
+    temp_file_path: str,
+    storage_key: str,
+    label: str,
+) -> bool:
+    try:
+        if not os.path.exists(temp_file_path):
+            logger.warning(f"{label} temp file not found: {temp_file_path}")
+            return False
+
+        file_size = os.path.getsize(temp_file_path)
+        logger.debug(f"{label} file size: {file_size} bytes")
+
+        await storage_fs.aupload_file(temp_file_path, storage_key)
+        logger.info(f"Successfully uploaded {label}: {storage_key}")
+        return True
+    except Exception as e:
+        logger.error(f"Error uploading {label} for workflow {workflow_run_id}: {e}")
+        return False
+    finally:
+        if os.path.exists(temp_file_path):
+            try:
+                os.remove(temp_file_path)
+                logger.debug(f"Cleaned up temp {label} file: {temp_file_path}")
+            except Exception as e:
+                logger.warning(f"Failed to clean up temp {label} file: {e}")
+
+
+async def process_workflow_completion(
+    _ctx,
+    workflow_run_id: int,
+    audio_temp_path: Optional[str] = None,
+    transcript_temp_path: Optional[str] = None,
+    user_audio_temp_path: Optional[str] = None,
+    bot_audio_temp_path: Optional[str] = None,
+):
+    """Process workflow completion: upload artifacts and run integrations.
+
+    This task combines audio upload, transcript upload, and webhook integrations
+    into a single sequential task to ensure integrations run after uploads complete.
+
+    Args:
+        _ctx: ARQ context (unused)
+        workflow_run_id: The workflow run ID
+        audio_temp_path: Optional path to temp audio file
+        transcript_temp_path: Optional path to temp transcript file
+        user_audio_temp_path: Optional path to temp user-track audio file
+        bot_audio_temp_path: Optional path to temp bot-track audio file
+    """
+    run_id = str(workflow_run_id)
+    set_current_run_id(run_id)
+
+    logger.info(f"Processing workflow completion for run {workflow_run_id}")
+
+    storage_backend = get_current_storage_backend()
+
+    # Step 1: Upload audio if provided
+    recordings_metadata: dict[str, dict] = {}
+
+    if audio_temp_path:
+        recording_url = f"recordings/{workflow_run_id}.wav"
+        logger.info(
+            f"Uploading mixed audio to {storage_backend.name} - workflow_run_id: {workflow_run_id}"
+        )
+        if await _upload_temp_file(
+            workflow_run_id, audio_temp_path, recording_url, "mixed audio"
+        ):
+            recordings_metadata["mixed"] = _recording_metadata(
+                recording_url, storage_backend.value, "mixed"
+            )
+            await db_client.update_workflow_run(
+                run_id=workflow_run_id,
+                recording_url=recording_url,
+                storage_backend=storage_backend.value,
+            )
+
+    if user_audio_temp_path:
+        user_recording_url = f"recordings/{workflow_run_id}/user.wav"
+        logger.info(
+            f"Uploading user audio to {storage_backend.name} - workflow_run_id: {workflow_run_id}"
+        )
+        if await _upload_temp_file(
+            workflow_run_id, user_audio_temp_path, user_recording_url, "user audio"
+        ):
+            recordings_metadata["user"] = _recording_metadata(
+                user_recording_url, storage_backend.value, "user"
+            )
+
+    if bot_audio_temp_path:
+        bot_recording_url = f"recordings/{workflow_run_id}/bot.wav"
+        logger.info(
+            f"Uploading bot audio to {storage_backend.name} - workflow_run_id: {workflow_run_id}"
+        )
+        if await _upload_temp_file(
+            workflow_run_id, bot_audio_temp_path, bot_recording_url, "bot audio"
+        ):
+            recordings_metadata["bot"] = _recording_metadata(
+                bot_recording_url, storage_backend.value, "bot"
+            )
+
+    if recordings_metadata:
+        await db_client.update_workflow_run(
+            run_id=workflow_run_id,
+            storage_backend=storage_backend.value,
+            extra={"recordings": recordings_metadata},
+        )
+
+    # Step 2: Upload transcript if provided
+    if transcript_temp_path:
+        try:
+            if os.path.exists(transcript_temp_path):
+                file_size = os.path.getsize(transcript_temp_path)
+                logger.debug(f"Transcript file size: {file_size} bytes")
+
+                transcript_url = f"transcripts/{workflow_run_id}.txt"
+                logger.info(
+                    f"Uploading transcript to {storage_backend.name} - workflow_run_id: {workflow_run_id}"
+                )
+
+                await storage_fs.aupload_file(transcript_temp_path, transcript_url)
+                await db_client.update_workflow_run(
+                    run_id=workflow_run_id,
+                    transcript_url=transcript_url,
+                    storage_backend=storage_backend.value,
+                )
+                logger.info(f"Successfully uploaded transcript: {transcript_url}")
+            else:
+                logger.warning(
+                    f"Transcript temp file not found: {transcript_temp_path}"
+                )
+        except Exception as e:
+            logger.error(
+                f"Error uploading transcript for workflow {workflow_run_id}: {e}"
+            )
+        finally:
+            if transcript_temp_path and os.path.exists(transcript_temp_path):
+                try:
+                    os.remove(transcript_temp_path)
+                    logger.debug(
+                        f"Cleaned up temp transcript file: {transcript_temp_path}"
+                    )
+                except Exception as e:
+                    logger.warning(f"Failed to clean up temp transcript file: {e}")
+
+    # Step 3: Run integrations including QA analysis (after uploads are complete)
+    try:
+        await run_integrations_post_workflow_run(_ctx, workflow_run_id)
+    except Exception as e:
+        logger.error(f"Error running integrations for workflow {workflow_run_id}: {e}")
+
+    # Step 4: Notify MPS after completion. MPS owns credit accounting.
+    try:
+        await report_completed_workflow_run_platform_usage(workflow_run_id)
+    except Exception as e:
+        logger.error(
+            f"Error reporting platform usage for workflow {workflow_run_id}: {e}"
+        )
+
+    logger.info(f"Completed workflow completion processing for run {workflow_run_id}")

api/tests/integrations/_run_pipeline_helpers.py

@@ -203,7 +203,7 @@ async def create_workflow_run_rows(
     Returns:
         Tuple of (workflow_run, user, workflow).
     """
-    from api.schemas.user_configuration import UserConfiguration
+    from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
 
     org = OrganizationModel(provider_id=f"test-org-{provider_id_suffix}")
     async_session.add(org)
@@ -218,7 +218,7 @@ async def create_workflow_run_rows(
 
     await db_session.update_user_configuration(
         user_id=user.id,
-        configuration=UserConfiguration.model_validate(USER_CONFIGURATION),
+        configuration=EffectiveAIModelConfiguration.model_validate(USER_CONFIGURATION),
     )
 
     workflow = await db_session.create_workflow(

api/tests/telephony/cloudonix/test_routes.py

@@ -0,0 +1,119 @@
+"""Regression tests for Cloudonix CDR webhook handling.
+
+A Cloudonix CDR webhook is a public, unauthenticated endpoint that parses
+arbitrary external JSON. A partial / malformed payload (missing ``session``,
+or a ``null`` ``session`` / ``disposition``) must produce a graceful error
+response, not an unhandled ``AttributeError`` (HTTP 500).
+"""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from starlette.requests import Request
+
+from api.services.telephony.providers.cloudonix.routes import handle_cloudonix_cdr
+from api.services.telephony.status_processor import StatusCallbackRequest
+
+
+def _json_request(body: bytes) -> Request:
+    async def receive():
+        return {"type": "http.request", "body": body, "more_body": False}
+
+    return Request(
+        {
+            "type": "http",
+            "method": "POST",
+            "scheme": "https",
+            "server": ("example.test", 443),
+            "path": "/api/v1/telephony/cloudonix/cdr",
+            "query_string": b"",
+            "headers": [(b"content-type", b"application/json")],
+        },
+        receive,
+    )
+
+
+@pytest.mark.asyncio
+async def test_cdr_route_handles_payload_without_session():
+    """A CDR payload missing the ``session`` object returns a graceful error
+    instead of raising ``AttributeError`` on ``None.get("token")``."""
+    request = _json_request(b'{"domain": "acme.cloudonix.io", "disposition": "ANSWER"}')
+
+    with patch(
+        "api.services.telephony.providers.cloudonix.routes.db_client"
+    ) as db_client:
+        db_client.get_workflow_run_by_call_id = AsyncMock(return_value=None)
+
+        result = await handle_cloudonix_cdr(request)
+
+    assert result == {"status": "error", "message": "Missing call_id field"}
+
+
+@pytest.mark.asyncio
+async def test_cdr_route_handles_null_session():
+    """A CDR payload with an explicit ``null`` session is handled gracefully."""
+    request = _json_request(b'{"domain": "acme.cloudonix.io", "session": null}')
+
+    with patch(
+        "api.services.telephony.providers.cloudonix.routes.db_client"
+    ) as db_client:
+        db_client.get_workflow_run_by_call_id = AsyncMock(return_value=None)
+
+        result = await handle_cloudonix_cdr(request)
+
+    assert result == {"status": "error", "message": "Missing call_id field"}
+
+
+@pytest.mark.asyncio
+async def test_cdr_route_handles_string_session():
+    """A CDR payload with a non-object session is handled gracefully."""
+    request = _json_request(b'{"domain": "acme.cloudonix.io", "session": "abc"}')
+
+    with patch(
+        "api.services.telephony.providers.cloudonix.routes.db_client"
+    ) as db_client:
+        db_client.get_workflow_run_by_call_id = AsyncMock(return_value=None)
+
+        result = await handle_cloudonix_cdr(request)
+
+    assert result == {"status": "error", "message": "Missing call_id field"}
+
+
+def test_from_cloudonix_cdr_tolerates_missing_session_and_disposition():
+    """``from_cloudonix_cdr`` must not crash on a partial CDR payload."""
+    # Missing both session and disposition.
+    req = StatusCallbackRequest.from_cloudonix_cdr({"domain": "acme.cloudonix.io"})
+    assert req.call_id == ""
+    assert req.status == ""
+
+    # Explicit null values.
+    req = StatusCallbackRequest.from_cloudonix_cdr(
+        {"session": None, "disposition": None}
+    )
+    assert req.call_id == ""
+    assert req.status == ""
+
+
+def test_from_cloudonix_cdr_tolerates_string_session():
+    """``from_cloudonix_cdr`` treats a non-object session as missing call_id."""
+    req = StatusCallbackRequest.from_cloudonix_cdr(
+        {"session": "abc", "disposition": "ANSWER"}
+    )
+    assert req.call_id == ""
+    assert req.status == "completed"
+
+
+def test_from_cloudonix_cdr_maps_disposition_and_session_token():
+    """Normal, well-formed CDR payloads still map correctly."""
+    req = StatusCallbackRequest.from_cloudonix_cdr(
+        {
+            "session": {"token": "abc123"},
+            "disposition": "BUSY",
+            "from": "+15551230001",
+            "to": "+15551230002",
+            "billsec": 12,
+        }
+    )
+    assert req.call_id == "abc123"
+    assert req.status == "busy"
+    assert req.duration == "12"

api/tests/test_ai_model_configuration_v2.py

@@ -0,0 +1,459 @@
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from pydantic import ValidationError
+
+from api.schemas.ai_model_configuration import (
+    DograhManagedAIModelConfiguration,
+    EffectiveAIModelConfiguration,
+    OrganizationAIModelConfigurationResponse,
+    OrganizationAIModelConfigurationV2,
+    compile_ai_model_configuration_v2,
+)
+from api.services.configuration.ai_model_configuration import (
+    WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY,
+    check_for_masked_keys_in_ai_model_configuration_v2,
+    convert_legacy_ai_model_configuration_to_v2,
+    mask_ai_model_configuration_v2,
+    merge_ai_model_configuration_v2_secrets,
+    migrate_workflow_configuration_model_override_to_v2,
+)
+from api.services.configuration.check_validity import UserConfigurationValidator
+from api.services.configuration.masking import mask_key
+from api.services.configuration.registry import (
+    DeepgramSTTConfiguration,
+    DograhLLMService,
+    DograhSTTService,
+    DograhTTSService,
+    ElevenlabsTTSConfiguration,
+    GoogleLLMService,
+    GoogleRealtimeLLMConfiguration,
+    OpenAIEmbeddingsConfiguration,
+    OpenAILLMService,
+)
+
+
+def test_dograh_v2_compiles_to_effective_managed_pipeline_with_embeddings():
+    config = OrganizationAIModelConfigurationV2(
+        mode="dograh",
+        dograh=DograhManagedAIModelConfiguration(
+            api_key="mps-secret",
+            voice="default",
+            speed=1.2,
+            language="multi",
+        ),
+    )
+
+    effective = compile_ai_model_configuration_v2(config)
+
+    assert effective.is_realtime is False
+    assert effective.llm.provider == "dograh"
+    assert effective.llm.model == "default"
+    assert effective.tts.provider == "dograh"
+    assert effective.tts.speed == 1.2
+    assert effective.stt.provider == "dograh"
+    assert effective.stt.language == "multi"
+    assert effective.embeddings.provider == "dograh"
+    assert effective.embeddings.model == "default"
+    assert effective.managed_service_version == 2
+
+
+def test_dograh_v2_rejects_non_predefined_speed():
+    with pytest.raises(ValidationError):
+        OrganizationAIModelConfigurationV2(
+            mode="dograh",
+            dograh=DograhManagedAIModelConfiguration(
+                api_key="mps-secret",
+                speed=1.5,
+            ),
+        )
+
+
+def test_byok_v2_rejects_dograh_provider():
+    with pytest.raises(ValidationError):
+        OrganizationAIModelConfigurationV2.model_validate(
+            {
+                "mode": "byok",
+                "byok": {
+                    "mode": "pipeline",
+                    "pipeline": {
+                        "llm": {
+                            "provider": "dograh",
+                            "api_key": "mps-secret",
+                            "model": "default",
+                        },
+                        "tts": {
+                            "provider": "dograh",
+                            "api_key": "mps-secret",
+                            "model": "default",
+                            "voice": "default",
+                        },
+                        "stt": {
+                            "provider": "dograh",
+                            "api_key": "mps-secret",
+                            "model": "default",
+                        },
+                    },
+                },
+            }
+        )
+
+
+@pytest.mark.asyncio
+async def test_byok_realtime_validator_does_not_require_stt_or_tts():
+    config = OrganizationAIModelConfigurationV2.model_validate(
+        {
+            "mode": "byok",
+            "byok": {
+                "mode": "realtime",
+                "realtime": {
+                    "realtime": {
+                        "provider": "google_realtime",
+                        "api_key": "google-realtime-key",
+                        "model": "gemini-3.1-flash-live-preview",
+                        "voice": "Puck",
+                        "language": "en",
+                    },
+                    "llm": {
+                        "provider": "google",
+                        "api_key": "google-llm-key",
+                        "model": "gemini-2.0-flash",
+                    },
+                },
+            },
+        }
+    )
+    effective = compile_ai_model_configuration_v2(config)
+
+    assert effective.is_realtime is True
+    assert effective.stt is None
+    assert effective.tts is None
+    assert await UserConfigurationValidator().validate(effective) == {
+        "status": [{"model": "all", "message": "ok"}]
+    }
+
+
+@pytest.mark.asyncio
+async def test_pipeline_validator_requires_stt_and_tts_when_not_realtime():
+    effective = EffectiveAIModelConfiguration(
+        llm=GoogleLLMService(
+            provider="google",
+            api_key="google-llm-key",
+            model="gemini-2.0-flash",
+        ),
+        realtime=GoogleRealtimeLLMConfiguration(
+            provider="google_realtime",
+            api_key="google-realtime-key",
+            model="gemini-3.1-flash-live-preview",
+            voice="Puck",
+            language="en",
+        ),
+        is_realtime=False,
+    )
+
+    with pytest.raises(ValueError) as exc_info:
+        await UserConfigurationValidator().validate(effective)
+
+    assert exc_info.value.args[0] == [
+        {"model": "stt", "message": "API key is missing"},
+        {"model": "tts", "message": "API key is missing"},
+    ]
+
+
+def test_masked_dograh_key_is_preserved_when_saving_same_mode():
+    existing = OrganizationAIModelConfigurationV2(
+        mode="dograh",
+        dograh=DograhManagedAIModelConfiguration(api_key="mps-real-secret"),
+    )
+    incoming = OrganizationAIModelConfigurationV2(
+        mode="dograh",
+        dograh=DograhManagedAIModelConfiguration(api_key=mask_key("mps-real-secret")),
+    )
+
+    merged = merge_ai_model_configuration_v2_secrets(incoming, existing)
+
+    assert merged.dograh.api_key == "mps-real-secret"
+    check_for_masked_keys_in_ai_model_configuration_v2(merged)
+
+
+def test_masked_v2_configuration_masks_nested_service_keys():
+    config = OrganizationAIModelConfigurationV2(
+        mode="byok",
+        byok={
+            "mode": "pipeline",
+            "pipeline": {
+                "llm": {
+                    "provider": "openai",
+                    "api_key": "sk-real-secret",
+                    "model": "gpt-4.1",
+                },
+                "tts": {
+                    "provider": "elevenlabs",
+                    "api_key": "el-real-secret",
+                    "model": "eleven_flash_v2_5",
+                    "voice": "Rachel",
+                },
+                "stt": {
+                    "provider": "deepgram",
+                    "api_key": "dg-real-secret",
+                    "model": "nova-3-general",
+                },
+            },
+        },
+    )
+
+    masked = mask_ai_model_configuration_v2(config)
+
+    assert masked["byok"]["pipeline"]["llm"]["api_key"] == mask_key("sk-real-secret")
+    assert masked["byok"]["pipeline"]["tts"]["api_key"] == mask_key("el-real-secret")
+    assert masked["byok"]["pipeline"]["stt"]["api_key"] == mask_key("dg-real-secret")
+
+
+def test_legacy_all_dograh_pipeline_converts_to_dograh_v2():
+    legacy = EffectiveAIModelConfiguration(
+        llm=DograhLLMService(
+            provider="dograh",
+            api_key=["mps-secret"],
+            model="default",
+        ),
+        tts=DograhTTSService(
+            provider="dograh",
+            api_key=["mps-secret"],
+            model="default",
+            voice="default",
+            speed=1.0,
+        ),
+        stt=DograhSTTService(
+            provider="dograh",
+            api_key=["mps-secret"],
+            model="default",
+            language="multi",
+        ),
+    )
+
+    config = convert_legacy_ai_model_configuration_to_v2(legacy)
+
+    assert config.mode == "dograh"
+    assert config.dograh.api_key == "mps-secret"
+
+
+def test_legacy_mixed_dograh_pipeline_converts_to_dograh_v2():
+    legacy = EffectiveAIModelConfiguration(
+        llm=OpenAILLMService(
+            provider="openai",
+            api_key="sk-llm",
+            model="gpt-4.1",
+        ),
+        tts=DograhTTSService(
+            provider="dograh",
+            api_key="mps-tts",
+            model="default",
+            voice="default",
+        ),
+        stt=DograhSTTService(
+            provider="dograh",
+            api_key="mps-stt",
+            model="default",
+        ),
+        embeddings=OpenAIEmbeddingsConfiguration(
+            provider="openai",
+            api_key="sk-emb",
+            model="text-embedding-3-small",
+        ),
+    )
+
+    config = convert_legacy_ai_model_configuration_to_v2(legacy)
+
+    assert config.mode == "dograh"
+    assert config.dograh.api_key == "mps-tts"
+    assert config.dograh.voice == "default"
+
+
+def test_legacy_byok_pipeline_converts_to_byok_v2():
+    legacy = EffectiveAIModelConfiguration(
+        llm=OpenAILLMService(
+            provider="openai",
+            api_key="sk-llm",
+            model="gpt-4.1",
+        ),
+        tts=ElevenlabsTTSConfiguration(
+            provider="elevenlabs",
+            api_key="el-tts",
+            model="eleven_flash_v2_5",
+            voice="Rachel",
+        ),
+        stt=DeepgramSTTConfiguration(
+            provider="deepgram",
+            api_key="dg-stt",
+            model="nova-3-general",
+        ),
+        embeddings=OpenAIEmbeddingsConfiguration(
+            provider="openai",
+            api_key="sk-emb",
+            model="text-embedding-3-small",
+        ),
+    )
+
+    config = convert_legacy_ai_model_configuration_to_v2(legacy)
+
+    assert config.mode == "byok"
+    assert config.byok.mode == "pipeline"
+    assert config.byok.pipeline.llm.provider == "openai"
+    assert config.byok.pipeline.tts.provider == "elevenlabs"
+
+
+def test_workflow_model_override_migration_removes_v1_override_and_sets_v2():
+    base = EffectiveAIModelConfiguration(
+        llm=OpenAILLMService(
+            provider="openai",
+            api_key="sk-llm",
+            model="gpt-4.1",
+        ),
+        tts=ElevenlabsTTSConfiguration(
+            provider="elevenlabs",
+            api_key="el-tts",
+            model="eleven_flash_v2_5",
+            voice="Rachel",
+        ),
+        stt=DeepgramSTTConfiguration(
+            provider="deepgram",
+            api_key="dg-stt",
+            model="nova-3-general",
+        ),
+    )
+    workflow_configurations = {
+        "ambient_noise_configuration": {"enabled": False},
+        "model_overrides": {
+            "tts": {
+                "provider": "dograh",
+                "api_key": "mps-workflow",
+                "model": "default",
+                "voice": "default",
+            }
+        },
+    }
+
+    migrated, changed = migrate_workflow_configuration_model_override_to_v2(
+        workflow_configurations,
+        base,
+    )
+
+    assert changed is True
+    assert "model_overrides" not in migrated
+    assert migrated["ambient_noise_configuration"] == {"enabled": False}
+    v2_override = migrated[WORKFLOW_MODEL_CONFIGURATION_V2_OVERRIDE_KEY]
+    assert v2_override["mode"] == "dograh"
+    assert v2_override["dograh"]["api_key"] == "mps-workflow"
+
+
+def test_workflow_model_override_migration_removes_invalid_v1_override_marker():
+    base = EffectiveAIModelConfiguration()
+    workflow_configurations = {
+        "ambient_noise_configuration": {"enabled": False},
+        "model_overrides": None,
+    }
+
+    migrated, changed = migrate_workflow_configuration_model_override_to_v2(
+        workflow_configurations,
+        base,
+    )
+
+    assert changed is True
+    assert "model_overrides" not in migrated
+    assert migrated["ambient_noise_configuration"] == {"enabled": False}
+
+
+@pytest.mark.asyncio
+async def test_migrate_model_configuration_v2_initializes_hosted_mps_billing(
+    monkeypatch,
+):
+    from api.routes import organization as organization_routes
+
+    legacy = EffectiveAIModelConfiguration(
+        llm=DograhLLMService(
+            provider="dograh",
+            api_key=["mps-secret"],
+            model="default",
+        ),
+        tts=DograhTTSService(
+            provider="dograh",
+            api_key=["mps-secret"],
+            model="default",
+            voice="default",
+        ),
+        stt=DograhSTTService(
+            provider="dograh",
+            api_key=["mps-secret"],
+            model="default",
+        ),
+    )
+    expected_response = OrganizationAIModelConfigurationResponse(
+        configuration={"version": 2, "mode": "dograh"},
+        effective_configuration={},
+        source="organization_v2",
+    )
+
+    class FakeValidator:
+        async def validate(self, *args, **kwargs):
+            return {"status": [{"model": "all", "message": "ok"}]}
+
+    ensure_billing = AsyncMock(return_value={"billing_mode": "v2"})
+    upsert = AsyncMock()
+    migrate_workflows = AsyncMock()
+
+    monkeypatch.setattr(organization_routes, "DEPLOYMENT_MODE", "saas")
+    monkeypatch.setattr(
+        organization_routes,
+        "get_organization_ai_model_configuration_v2",
+        AsyncMock(return_value=None),
+    )
+    monkeypatch.setattr(
+        organization_routes.db_client,
+        "get_user_configurations",
+        AsyncMock(return_value=legacy),
+    )
+    monkeypatch.setattr(
+        organization_routes,
+        "UserConfigurationValidator",
+        lambda: FakeValidator(),
+    )
+    monkeypatch.setattr(
+        organization_routes,
+        "ensure_hosted_mps_billing_account_v2",
+        ensure_billing,
+    )
+    monkeypatch.setattr(
+        organization_routes,
+        "upsert_organization_ai_model_configuration_v2",
+        upsert,
+    )
+    monkeypatch.setattr(
+        organization_routes,
+        "migrate_workflow_model_configurations_to_v2",
+        migrate_workflows,
+    )
+    monkeypatch.setattr(
+        organization_routes,
+        "_model_configuration_v2_response",
+        AsyncMock(return_value=expected_response),
+    )
+
+    user = SimpleNamespace(
+        id=7,
+        provider_id="provider-123",
+        selected_organization_id=42,
+    )
+
+    response = await organization_routes.migrate_model_configuration_v2(
+        force=False,
+        user=user,
+    )
+
+    ensure_billing.assert_awaited_once_with(42, created_by="provider-123")
+    upsert.assert_awaited_once()
+    migrate_workflows.assert_awaited_once_with(
+        organization_id=42,
+        fallback_user_config=legacy,
+    )
+    assert response == expected_response

api/tests/test_auth_depends.py

@@ -0,0 +1,68 @@
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from api.services.auth import depends as auth_depends
+
+
+@pytest.mark.asyncio
+async def test_get_user_initializes_hosted_mps_billing_for_new_org(monkeypatch):
+    stack_user = {
+        "id": "stack-user-1",
+        "selected_team_id": "team-1",
+        "primary_email_verified": False,
+    }
+    user = SimpleNamespace(
+        id=7,
+        email=None,
+        provider_id="stack-user-1",
+        selected_organization_id=None,
+    )
+    organization = SimpleNamespace(id=42)
+    existing_config = SimpleNamespace(llm=object(), tts=None, stt=None)
+
+    ensure_billing = AsyncMock(return_value={"billing_mode": "v2"})
+
+    monkeypatch.setattr(auth_depends, "AUTH_PROVIDER", "stack")
+    monkeypatch.setattr(
+        auth_depends.stackauth,
+        "get_user",
+        AsyncMock(return_value=stack_user),
+    )
+    monkeypatch.setattr(
+        auth_depends.db_client,
+        "get_or_create_user_by_provider_id",
+        AsyncMock(return_value=(user, False)),
+    )
+    monkeypatch.setattr(
+        auth_depends.db_client,
+        "get_or_create_organization_by_provider_id",
+        AsyncMock(return_value=(organization, True)),
+    )
+    monkeypatch.setattr(
+        auth_depends.db_client,
+        "add_user_to_organization",
+        AsyncMock(),
+    )
+    monkeypatch.setattr(
+        auth_depends.db_client,
+        "update_user_selected_organization",
+        AsyncMock(),
+    )
+    monkeypatch.setattr(
+        auth_depends.db_client,
+        "get_user_configurations",
+        AsyncMock(return_value=existing_config),
+    )
+    monkeypatch.setattr(
+        auth_depends,
+        "ensure_hosted_mps_billing_account_v2",
+        ensure_billing,
+    )
+
+    result = await auth_depends.get_user(authorization="Bearer token")
+
+    assert result is user
+    assert result.selected_organization_id == 42
+    ensure_billing.assert_awaited_once_with(42, created_by="stack-user-1")

api/tests/test_cartesia_tts_service_factory.py

@@ -0,0 +1,77 @@
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from api.services.configuration.registry import (
+    CARTESIA_TTS_MODELS,
+    CartesiaTTSConfiguration,
+    ServiceProviders,
+)
+from api.services.pipecat.service_factory import create_tts_service
+
+
+def test_cartesia_tts_configuration_defaults_to_sonic_3_5():
+    config = CartesiaTTSConfiguration(api_key="test-key")
+
+    assert config.provider == ServiceProviders.CARTESIA
+    assert config.model == "sonic-3.5"
+    assert CARTESIA_TTS_MODELS == ["sonic-3.5", "sonic-3"]
+
+
+def test_create_cartesia_tts_service_passes_selected_model():
+    user_config = SimpleNamespace(
+        tts=SimpleNamespace(
+            provider=ServiceProviders.CARTESIA.value,
+            api_key="test-key",
+            model="sonic-3.5",
+            voice="test-voice-id",
+            speed=1.0,
+            volume=1.0,
+        )
+    )
+    audio_config = SimpleNamespace(
+        transport_out_sample_rate=24000,
+        transport_in_sample_rate=16000,
+    )
+
+    with patch(
+        "api.services.pipecat.service_factory.CartesiaTTSService"
+    ) as mock_service:
+        create_tts_service(user_config, audio_config)
+
+    assert mock_service.call_count == 1
+    kwargs = mock_service.call_args.kwargs
+    assert kwargs["api_key"] == "test-key"
+    assert kwargs["settings"].model == "sonic-3.5"
+    assert kwargs["settings"].voice == "test-voice-id"
+
+
+def test_cartesia_tts_configuration_default_language_is_english():
+    config = CartesiaTTSConfiguration(api_key="test-key")
+
+    assert config.language == "en"
+
+
+def test_create_cartesia_tts_service_passes_language_to_settings():
+    user_config = SimpleNamespace(
+        tts=SimpleNamespace(
+            provider=ServiceProviders.CARTESIA.value,
+            api_key="test-key",
+            model="sonic-3.5",
+            voice="test-voice-id",
+            speed=1.0,
+            volume=1.0,
+            language="tr",
+        )
+    )
+    audio_config = SimpleNamespace(
+        transport_out_sample_rate=24000,
+        transport_in_sample_rate=16000,
+    )
+
+    with patch(
+        "api.services.pipecat.service_factory.CartesiaTTSService"
+    ) as mock_service:
+        create_tts_service(user_config, audio_config)
+
+    kwargs = mock_service.call_args.kwargs
+    assert kwargs["settings"].language == "tr"

api/tests/test_cost_calculator.py

@@ -1,31 +0,0 @@
-from api.services.pricing.cost_calculator import cost_calculator
-
-
-def test_cost_calculator():
-    """Test function to verify cost calculation works"""
-    sample_usage = {
-        "llm": {
-            "OpenAILLMService#0|||gpt-4.1-mini": {
-                "prompt_tokens": 45380,
-                "completion_tokens": 496,
-                "total_tokens": 45876,
-                "cache_read_input_tokens": 0,
-                "cache_creation_input_tokens": 0,
-            }
-        },
-        "tts": {"ElevenLabsTTSService#0|||eleven_flash_v2_5": 2399},
-        "stt": {"DeepgramSTTService#0|||nova-3-general": 177.21536946296692},
-        "call_duration_seconds": 179,
-    }
-
-    result = cost_calculator.calculate_total_cost(sample_usage)
-    assert result["llm_cost"] == 45380 * 0.40 / 1_000_000 + 496 * 1.60 / 1_000_000
-    assert result["tts_cost"] == 2399 * 0.0256 / 1_000
-    assert result["stt_cost"] == 177.21536946296692 / 60 * 0.0077
-    assert (
-        abs(
-            result["total"]
-            - (result["llm_cost"] + result["tts_cost"] + result["stt_cost"])
-        )
-        < 1e-10
-    )

api/tests/test_deepgram_flux_service_factory.py

@@ -0,0 +1,70 @@
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from pipecat.services.settings import NOT_GIVEN
+from pipecat.transcriptions.language import Language
+
+from api.services.configuration.registry import (
+    DeepgramSTTConfiguration,
+    ServiceProviders,
+)
+from api.services.pipecat.audio_config import AudioConfig
+from api.services.pipecat.service_factory import create_stt_service
+
+
+def test_deepgram_stt_schema_includes_flux_multilingual_language_options():
+    language_schema = DeepgramSTTConfiguration.model_json_schema()["properties"][
+        "language"
+    ]
+
+    assert "flux-general-multi" in language_schema["model_options"]
+    assert "multi" in language_schema["model_options"]["flux-general-multi"]
+    assert "es" in language_schema["model_options"]["flux-general-multi"]
+
+
+def test_create_deepgram_flux_multi_uses_flux_service_with_language_hint():
+    user_config = SimpleNamespace(
+        stt=SimpleNamespace(
+            provider=ServiceProviders.DEEPGRAM.value,
+            api_key="test-key",
+            model="flux-general-multi",
+            language="es",
+        )
+    )
+    audio_config = AudioConfig(
+        transport_in_sample_rate=16000,
+        transport_out_sample_rate=16000,
+    )
+
+    with patch(
+        "api.services.pipecat.service_factory.DeepgramFluxSTTService"
+    ) as mock_service:
+        create_stt_service(user_config, audio_config)
+
+    kwargs = mock_service.call_args.kwargs
+    assert kwargs["settings"].model == "flux-general-multi"
+    assert kwargs["settings"].language_hints == [Language.ES]
+
+
+def test_create_deepgram_flux_multi_omits_auto_detect_language_hint():
+    user_config = SimpleNamespace(
+        stt=SimpleNamespace(
+            provider=ServiceProviders.DEEPGRAM.value,
+            api_key="test-key",
+            model="flux-general-multi",
+            language="multi",
+        )
+    )
+    audio_config = AudioConfig(
+        transport_in_sample_rate=16000,
+        transport_out_sample_rate=16000,
+    )
+
+    with patch(
+        "api.services.pipecat.service_factory.DeepgramFluxSTTService"
+    ) as mock_service:
+        create_stt_service(user_config, audio_config)
+
+    kwargs = mock_service.call_args.kwargs
+    assert kwargs["settings"].model == "flux-general-multi"
+    assert kwargs["settings"].language_hints is NOT_GIVEN

api/tests/test_dograh_managed_correlation.py

@@ -0,0 +1,146 @@
+import json
+
+import pytest
+from openai._types import NOT_GIVEN as OPENAI_NOT_GIVEN
+from pipecat.frames.frames import TTSStartedFrame
+from pipecat.services.dograh.llm import DograhLLMService
+from pipecat.services.dograh.stt import DograhSTTService
+from pipecat.services.dograh.tts import DograhTTSService
+from pipecat.services.openai.base_llm import OpenAILLMSettings
+from websockets.protocol import State
+
+
+class _FakeWebSocket:
+    def __init__(self):
+        self.state = State.OPEN
+        self.messages: list[dict] = []
+
+    async def send(self, message: str) -> None:
+        self.messages.append(json.loads(message))
+
+    async def close(self, *args, **kwargs) -> None:
+        self.state = State.CLOSED
+
+
+class _IterableFakeWebSocket(_FakeWebSocket):
+    def __init__(self, incoming_messages: list[dict]):
+        super().__init__()
+        self.incoming_messages = [json.dumps(message) for message in incoming_messages]
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> str:
+        if not self.incoming_messages:
+            raise StopAsyncIteration
+        return self.incoming_messages.pop(0)
+
+
+def test_dograh_llm_uses_explicit_mps_correlation_id():
+    service = DograhLLMService(
+        api_key="mps-secret",
+        correlation_id="mps-corr-123",
+        settings=OpenAILLMSettings(model="default"),
+    )
+    service._start_metadata = {"workflow_run_id": 99}
+
+    params = service.build_chat_completion_params(
+        {
+            "messages": [],
+            "tools": OPENAI_NOT_GIVEN,
+            "tool_choice": OPENAI_NOT_GIVEN,
+        }
+    )
+
+    assert params["metadata"]["correlation_id"] == "mps-corr-123"
+    assert params["metadata"]["mps_billing_version"] == "2"
+
+
+@pytest.mark.asyncio
+async def test_dograh_stt_config_uses_explicit_mps_correlation_id(monkeypatch):
+    fake_ws = _FakeWebSocket()
+
+    async def fake_connect(url, additional_headers):
+        return fake_ws
+
+    monkeypatch.setattr(
+        "pipecat.services.dograh.stt.websocket_connect",
+        fake_connect,
+    )
+
+    service = DograhSTTService(
+        api_key="mps-secret",
+        correlation_id="mps-corr-123",
+        sample_rate=16000,
+    )
+    service._start_metadata = {"workflow_run_id": 99}
+
+    await service._connect_websocket()
+
+    assert fake_ws.messages[0]["type"] == "config"
+    assert fake_ws.messages[0]["correlation_id"] == "mps-corr-123"
+    assert fake_ws.messages[0]["mps_billing_version"] == "2"
+
+
+@pytest.mark.asyncio
+async def test_dograh_tts_messages_use_explicit_mps_correlation_id(monkeypatch):
+    fake_ws = _FakeWebSocket()
+
+    async def fake_connect(url, additional_headers):
+        return fake_ws
+
+    monkeypatch.setattr(
+        "pipecat.services.dograh.tts.websocket_connect",
+        fake_connect,
+    )
+
+    service = DograhTTSService(
+        api_key="mps-secret",
+        correlation_id="mps-corr-123",
+        sample_rate=24000,
+    )
+    service._start_metadata = {"workflow_run_id": 99}
+
+    await service._connect_websocket()
+    assert fake_ws.messages[0]["type"] == "config"
+    assert fake_ws.messages[0]["correlation_id"] == "mps-corr-123"
+    assert fake_ws.messages[0]["mps_billing_version"] == "2"
+
+    async def _noop(*args, **kwargs):
+        return None
+
+    service.audio_context_available = lambda context_id: False
+    service.create_audio_context = _noop
+    service.start_ttfb_metrics = _noop
+    service.start_tts_usage_metrics = _noop
+
+    frames = []
+    async for frame in service.run_tts("hello", "ctx-1"):
+        frames.append(frame)
+
+    assert isinstance(frames[0], TTSStartedFrame)
+    assert fake_ws.messages[1]["type"] == "create_context"
+    assert fake_ws.messages[1]["correlation_id"] == "mps-corr-123"
+    assert fake_ws.messages[1]["mps_billing_version"] == "2"
+
+
+@pytest.mark.asyncio
+async def test_dograh_tts_final_for_missing_context_is_ignored():
+    service = DograhTTSService(api_key="mps-secret")
+    service._websocket = _IterableFakeWebSocket(
+        [{"type": "final", "context_id": "ctx-already-removed"}]
+    )
+    service._remote_initialized_context_ids.add("ctx-already-removed")
+
+    remove_calls = []
+
+    async def fake_remove_audio_context(context_id: str):
+        remove_calls.append(context_id)
+
+    service.audio_context_available = lambda context_id: False
+    service.remove_audio_context = fake_remove_audio_context
+
+    await service._receive_messages()
+
+    assert remove_calls == []
+    assert "ctx-already-removed" not in service._remote_initialized_context_ids

api/tests/test_from_number_pool_isolation.py

@@ -270,6 +270,12 @@ class TestDispatcherThreadsTelephonyConfig:
                 "api.services.campaign.campaign_call_dispatcher.get_backend_endpoints",
                 AsyncMock(return_value=("https://example.com", None)),
             ),
+            patch(
+                "api.services.campaign.campaign_call_dispatcher.authorize_workflow_run_start",
+                AsyncMock(
+                    return_value=SimpleNamespace(has_quota=True, error_message="")
+                ),
+            ),
         ):
             mock_db.get_workflow_by_id = AsyncMock(return_value=SimpleNamespace(id=1))
             mock_db.create_workflow_run = AsyncMock(return_value=workflow_run)

api/tests/test_grok_realtime_wrapper.py

@@ -7,7 +7,7 @@ from pipecat.processors.aggregators.llm_context import LLMContext
 from pipecat.processors.frame_processor import FrameDirection
 from pipecat.services.xai.realtime import events
 
-from api.schemas.user_configuration import UserConfiguration
+from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
 from api.services.configuration.registry import GrokRealtimeLLMConfiguration
 from api.services.pipecat.realtime.grok_realtime import (
     DograhGrokRealtimeLLMService,
@@ -120,7 +120,7 @@ async def test_completed_input_transcription_is_broadcast_as_finalized():
 
 
 def test_factory_creates_dograh_grok_realtime_service():
-    user_config = UserConfiguration(
+    effective_config = EffectiveAIModelConfiguration(
         is_realtime=True,
         realtime=GrokRealtimeLLMConfiguration(
             provider="grok_realtime",
@@ -131,7 +131,7 @@ def test_factory_creates_dograh_grok_realtime_service():
     )
 
     service = create_realtime_llm_service(
-        user_config,
+        effective_config,
         audio_config=SimpleNamespace(),
     )
 

api/tests/test_huggingface_stt_service_factory.py

@@ -0,0 +1,131 @@
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from api.services.configuration.check_validity import UserConfigurationValidator
+from api.services.configuration.registry import (
+    REGISTRY,
+    HuggingFaceLLMConfiguration,
+    HuggingFaceSTTConfiguration,
+    ServiceProviders,
+    ServiceType,
+)
+from api.services.pipecat.service_factory import (
+    create_llm_service,
+    create_stt_service,
+)
+
+
+def test_huggingface_stt_configuration_defaults_and_registry():
+    config = HuggingFaceSTTConfiguration(api_key="hf_test")
+
+    assert config.provider == ServiceProviders.HUGGINGFACE
+    assert config.model == "openai/whisper-large-v3-turbo"
+    assert config.base_url == "https://router.huggingface.co/hf-inference"
+    assert config.return_timestamps is False
+    assert (
+        REGISTRY[ServiceType.STT][ServiceProviders.HUGGINGFACE]
+        is HuggingFaceSTTConfiguration
+    )
+
+
+def test_huggingface_llm_configuration_defaults_and_registry():
+    config = HuggingFaceLLMConfiguration(api_key="hf_test")
+
+    assert config.provider == ServiceProviders.HUGGINGFACE
+    assert config.model == "openai/gpt-oss-120b:cerebras"
+    assert config.base_url == "https://router.huggingface.co/v1"
+    assert (
+        REGISTRY[ServiceType.LLM][ServiceProviders.HUGGINGFACE]
+        is HuggingFaceLLMConfiguration
+    )
+
+
+def test_create_huggingface_llm_service_uses_openai_compatible_router():
+    user_config = SimpleNamespace(
+        llm=SimpleNamespace(
+            provider=ServiceProviders.HUGGINGFACE.value,
+            api_key="hf_test",
+            model="deepseek-ai/DeepSeek-R1:fastest",
+            base_url="https://router.huggingface.co/v1",
+            bill_to="demo-org",
+        )
+    )
+
+    with patch(
+        "api.services.pipecat.service_factory.HuggingFaceLLMService"
+    ) as mock_service:
+        create_llm_service(user_config)
+
+    assert mock_service.call_count == 1
+    kwargs = mock_service.call_args.kwargs
+    assert kwargs["api_key"] == "hf_test"
+    assert kwargs["base_url"] == "https://router.huggingface.co/v1"
+    assert kwargs["bill_to"] == "demo-org"
+    assert kwargs["settings"].model == "deepseek-ai/DeepSeek-R1:fastest"
+    assert kwargs["settings"].temperature == 0.1
+
+
+def test_create_huggingface_stt_service_uses_hosted_defaults():
+    user_config = SimpleNamespace(
+        stt=SimpleNamespace(
+            provider=ServiceProviders.HUGGINGFACE.value,
+            api_key="hf_test",
+            model="openai/whisper-large-v3-turbo",
+            base_url="https://router.huggingface.co/hf-inference",
+            bill_to="demo-org",
+            return_timestamps=True,
+        )
+    )
+    audio_config = SimpleNamespace(transport_in_sample_rate=16000)
+
+    with patch(
+        "api.services.pipecat.service_factory.HuggingFaceSTTService"
+    ) as mock_service:
+        create_stt_service(user_config, audio_config)
+
+    assert mock_service.call_count == 1
+    kwargs = mock_service.call_args.kwargs
+    assert kwargs["api_key"] == "hf_test"
+    assert kwargs["base_url"] == "https://router.huggingface.co/hf-inference"
+    assert kwargs["bill_to"] == "demo-org"
+    assert kwargs["sample_rate"] == 16000
+    assert kwargs["settings"].model == "openai/whisper-large-v3-turbo"
+    assert kwargs["settings"].return_timestamps is True
+
+
+def test_validator_accepts_huggingface_stt_token_format():
+    validator = UserConfigurationValidator()
+
+    assert (
+        validator._validate_service(
+            HuggingFaceSTTConfiguration(api_key="hf_test"),
+            "stt",
+        )
+        == []
+    )
+    assert (
+        validator._validate_service(
+            HuggingFaceLLMConfiguration(api_key="hf_test"),
+            "llm",
+        )
+        == []
+    )
+
+
+def test_validator_rejects_non_huggingface_token_format():
+    validator = UserConfigurationValidator()
+
+    errors = validator._validate_service(
+        HuggingFaceSTTConfiguration(api_key="not-hf-token"),
+        "stt",
+    )
+
+    assert errors == [
+        {
+            "model": "stt",
+            "message": (
+                "Invalid Hugging Face API token format. Use a token that starts with "
+                "'hf_' and has Inference Providers permission."
+            ),
+        }
+    ]

api/tests/test_masked_key_rejection.py

@@ -1,10 +1,11 @@
+from types import SimpleNamespace
 from unittest.mock import AsyncMock, MagicMock, patch
 
 from fastapi import FastAPI
 from fastapi.testclient import TestClient
 
 from api.routes.user import router
-from api.schemas.user_configuration import UserConfiguration
+from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
 from api.services.auth.depends import get_user
 from api.services.configuration.masking import mask_key
 from api.services.configuration.registry import (
@@ -14,14 +15,14 @@ from api.services.configuration.registry import (
 )
 
 
-def _make_test_app():
+def _make_test_app(selected_organization_id=None):
     app = FastAPI()
     app.include_router(router)
 
     mock_user = MagicMock()
     mock_user.id = 1
     mock_user.is_superuser = False
-    mock_user.selected_organization_id = None
+    mock_user.selected_organization_id = selected_organization_id
 
     app.dependency_overrides[get_user] = lambda: mock_user
     return app
@@ -32,7 +33,7 @@ MASKED_KEY = mask_key(REAL_KEY)  # "**************************cdef"
 
 
 def _existing_openai_config():
-    return UserConfiguration(
+    return EffectiveAIModelConfiguration(
         llm=OpenAILLMService(
             provider="openai",
             api_key=REAL_KEY,
@@ -110,7 +111,7 @@ class TestMaskedKeyRejection:
         client = TestClient(app)
 
         new_key = "AIzaSyNewRealKey12345678"
-        updated = UserConfiguration(
+        updated = EffectiveAIModelConfiguration(
             llm=GoogleLLMService(
                 provider="google",
                 api_key=new_key,
@@ -177,7 +178,7 @@ class TestMaskedKeyRejection:
 
         real_credentials = '{"type":"service_account","project_id":"demo-project"}'
         masked_credentials = mask_key(real_credentials)
-        existing = UserConfiguration(
+        existing = EffectiveAIModelConfiguration(
             llm=GoogleVertexLLMConfiguration(
                 provider="google_vertex",
                 api_key=None,
@@ -210,3 +211,38 @@ class TestMaskedKeyRejection:
             )
 
             assert response.status_code == 200
+
+    def test_preference_only_update_does_not_validate_or_save_model_config(self):
+        """Saving a test phone number through the legacy endpoint must not touch models."""
+        app = _make_test_app(selected_organization_id=11)
+        client = TestClient(app)
+        preferences = SimpleNamespace(test_phone_number=None, timezone=None)
+
+        with (
+            patch("api.routes.user.db_client") as mock_db,
+            patch("api.routes.user.UserConfigurationValidator") as mock_validator,
+            patch(
+                "api.routes.user.get_organization_preferences",
+                new=AsyncMock(return_value=preferences),
+            ),
+            patch(
+                "api.routes.user.upsert_organization_preferences",
+                new=AsyncMock(return_value=preferences),
+            ) as upsert_preferences,
+        ):
+            existing = _existing_openai_config()
+            mock_db.get_user_configurations = AsyncMock(return_value=existing)
+            mock_db.update_user_configuration = AsyncMock()
+            mock_db.get_organization_by_id = AsyncMock(return_value=None)
+            mock_validator.return_value.validate = AsyncMock()
+
+            response = client.put(
+                "/user/configurations/user",
+                json={"test_phone_number": "+15551234567"},
+            )
+
+            assert response.status_code == 200
+            assert response.json()["test_phone_number"] == "+15551234567"
+            mock_db.update_user_configuration.assert_not_called()
+            mock_validator.return_value.validate.assert_not_called()
+            upsert_preferences.assert_awaited_once()

api/tests/test_mps_service_key_client.py

@@ -87,3 +87,387 @@ async def test_check_service_key_usage_uses_bearer_self_usage(monkeypatch):
             "Content-Type": "application/json",
         },
     )
+
+
+@pytest.mark.asyncio
+async def test_create_correlation_id_uses_bearer_auth(monkeypatch):
+    calls = []
+
+    class FakeAsyncClient:
+        def __init__(self, timeout):
+            self.timeout = timeout
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return None
+
+        async def post(self, url, json, headers):
+            calls.append(("POST", url, json, headers))
+            return _Response(200, {"correlation_id": "mps-corr-123"})
+
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.httpx.AsyncClient", FakeAsyncClient
+    )
+
+    client = MPSServiceKeyClient()
+
+    assert await client.create_correlation_id(
+        service_key="mps_sk_paid",
+        workflow_run_id=42,
+    ) == {"correlation_id": "mps-corr-123"}
+    assert calls == [
+        (
+            "POST",
+            f"{client.base_url}/api/v1/service-keys/correlation-id/self",
+            {"workflow_run_id": 42},
+            {
+                "Authorization": "Bearer mps_sk_paid",
+                "Content-Type": "application/json",
+            },
+        )
+    ]
+
+
+@pytest.mark.asyncio
+async def test_get_billing_account_status_uses_hosted_org_auth(monkeypatch):
+    calls = []
+
+    class FakeAsyncClient:
+        def __init__(self, timeout):
+            self.timeout = timeout
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return None
+
+        async def get(self, url, headers):
+            calls.append(("GET", url, headers))
+            return _Response(200, {"organization_id": 42, "billing_mode": "v2"})
+
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.httpx.AsyncClient", FakeAsyncClient
+    )
+    monkeypatch.setattr("api.services.mps_service_key_client.DEPLOYMENT_MODE", "saas")
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.DOGRAH_MPS_SECRET_KEY", "mps-secret"
+    )
+
+    client = MPSServiceKeyClient()
+
+    assert await client.get_billing_account_status(organization_id=42) == {
+        "organization_id": 42,
+        "billing_mode": "v2",
+    }
+    assert calls == [
+        (
+            "GET",
+            f"{client.base_url}/api/v1/billing/accounts/42/status",
+            {
+                "Content-Type": "application/json",
+                "X-Secret-Key": "mps-secret",
+                "X-Organization-Id": "42",
+            },
+        )
+    ]
+
+
+@pytest.mark.asyncio
+async def test_authorize_workflow_run_start_uses_hosted_org_auth(monkeypatch):
+    calls = []
+
+    class FakeAsyncClient:
+        def __init__(self, timeout):
+            self.timeout = timeout
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return None
+
+        async def post(self, url, json, headers):
+            calls.append(("POST", url, json, headers))
+            return _Response(
+                200,
+                {
+                    "allowed": True,
+                    "billing_mode": "v2",
+                    "remaining_credits": "25.0000",
+                    "correlation_id": "mps-corr-123",
+                },
+            )
+
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.httpx.AsyncClient", FakeAsyncClient
+    )
+    monkeypatch.setattr("api.services.mps_service_key_client.DEPLOYMENT_MODE", "saas")
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.DOGRAH_MPS_SECRET_KEY", "mps-secret"
+    )
+
+    client = MPSServiceKeyClient()
+
+    assert await client.authorize_workflow_run_start(
+        organization_id=42,
+        workflow_run_id=88,
+        service_key="mps_sk_paid",
+        require_correlation_id=True,
+        minimum_credits=0.1,
+        metadata={"workflow_id": 7},
+        created_by="provider-123",
+    ) == {
+        "allowed": True,
+        "billing_mode": "v2",
+        "remaining_credits": "25.0000",
+        "correlation_id": "mps-corr-123",
+    }
+    assert calls == [
+        (
+            "POST",
+            f"{client.base_url}/api/v1/billing/accounts/42/run-authorization",
+            {
+                "workflow_run_id": 88,
+                "service_key": "mps_sk_paid",
+                "require_correlation_id": True,
+                "minimum_credits": 0.1,
+                "metadata": {"workflow_id": 7},
+            },
+            {
+                "Content-Type": "application/json",
+                "X-Secret-Key": "mps-secret",
+                "X-Organization-Id": "42",
+            },
+        )
+    ]
+
+
+@pytest.mark.asyncio
+async def test_ensure_billing_account_v2_uses_balance_endpoint(monkeypatch):
+    calls = []
+
+    class FakeAsyncClient:
+        def __init__(self, timeout):
+            self.timeout = timeout
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return None
+
+        async def get(self, url, headers):
+            calls.append(("GET", url, headers))
+            return _Response(
+                200,
+                {
+                    "id": 7,
+                    "organization_id": 42,
+                    "billing_mode": "v2",
+                    "cached_balance_credits": "0.0000",
+                    "currency": "USD",
+                },
+            )
+
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.httpx.AsyncClient", FakeAsyncClient
+    )
+    monkeypatch.setattr("api.services.mps_service_key_client.DEPLOYMENT_MODE", "saas")
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.DOGRAH_MPS_SECRET_KEY", "mps-secret"
+    )
+
+    client = MPSServiceKeyClient()
+
+    assert await client.ensure_billing_account_v2(
+        organization_id=42,
+        created_by="provider-123",
+    ) == {
+        "id": 7,
+        "organization_id": 42,
+        "billing_mode": "v2",
+        "cached_balance_credits": "0.0000",
+        "currency": "USD",
+    }
+    assert calls == [
+        (
+            "GET",
+            f"{client.base_url}/api/v1/billing/accounts/42/balance",
+            {
+                "Content-Type": "application/json",
+                "X-Secret-Key": "mps-secret",
+                "X-Organization-Id": "42",
+            },
+        )
+    ]
+
+
+@pytest.mark.asyncio
+async def test_get_credit_ledger_sends_page_and_limit(monkeypatch):
+    calls = []
+
+    class FakeAsyncClient:
+        def __init__(self, timeout):
+            self.timeout = timeout
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return None
+
+        async def get(self, url, params, headers):
+            calls.append(("GET", url, params, headers))
+            return _Response(
+                200,
+                {
+                    "account": {"organization_id": 42},
+                    "ledger_entries": [],
+                    "total_count": 0,
+                    "page": 3,
+                    "limit": 25,
+                    "total_pages": 0,
+                },
+            )
+
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.httpx.AsyncClient", FakeAsyncClient
+    )
+    monkeypatch.setattr("api.services.mps_service_key_client.DEPLOYMENT_MODE", "saas")
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.DOGRAH_MPS_SECRET_KEY", "mps-secret"
+    )
+
+    client = MPSServiceKeyClient()
+
+    assert await client.get_credit_ledger(
+        organization_id=42,
+        page=3,
+        limit=25,
+    ) == {
+        "account": {"organization_id": 42},
+        "ledger_entries": [],
+        "total_count": 0,
+        "page": 3,
+        "limit": 25,
+        "total_pages": 0,
+    }
+    assert calls == [
+        (
+            "GET",
+            f"{client.base_url}/api/v1/billing/accounts/42/ledger",
+            {"page": 3, "limit": 25},
+            {
+                "Content-Type": "application/json",
+                "X-Secret-Key": "mps-secret",
+                "X-Organization-Id": "42",
+            },
+        )
+    ]
+
+
+@pytest.mark.asyncio
+async def test_report_platform_usage_uses_hosted_secret_auth(monkeypatch):
+    calls = []
+
+    class FakeAsyncClient:
+        def __init__(self, timeout):
+            self.timeout = timeout
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return None
+
+        async def post(self, url, json, headers):
+            calls.append(("POST", url, json, headers))
+            return _Response(200, {"metered": True})
+
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.httpx.AsyncClient", FakeAsyncClient
+    )
+    monkeypatch.setattr("api.services.mps_service_key_client.DEPLOYMENT_MODE", "saas")
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.DOGRAH_MPS_SECRET_KEY", "mps-secret"
+    )
+
+    client = MPSServiceKeyClient()
+
+    assert await client.report_platform_usage(
+        organization_id=42,
+        correlation_id="mps-corr-123",
+        workflow_run_id=123,
+        metadata={"source": "workflow_run_completion"},
+    ) == {"metered": True}
+    assert calls == [
+        (
+            "POST",
+            f"{client.base_url}/api/v1/billing/accounts/42/platform-usage",
+            {
+                "correlation_id": "mps-corr-123",
+                "workflow_run_id": 123,
+                "metadata": {"source": "workflow_run_completion"},
+            },
+            {
+                "Content-Type": "application/json",
+                "X-Secret-Key": "mps-secret",
+                "X-Organization-Id": "42",
+            },
+        )
+    ]
+
+
+@pytest.mark.asyncio
+async def test_report_platform_usage_sends_duration_without_correlation(monkeypatch):
+    calls = []
+
+    class FakeAsyncClient:
+        def __init__(self, timeout):
+            self.timeout = timeout
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return None
+
+        async def post(self, url, json, headers):
+            calls.append(("POST", url, json, headers))
+            return _Response(200, {"metered": True})
+
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.httpx.AsyncClient", FakeAsyncClient
+    )
+    monkeypatch.setattr("api.services.mps_service_key_client.DEPLOYMENT_MODE", "saas")
+    monkeypatch.setattr(
+        "api.services.mps_service_key_client.DOGRAH_MPS_SECRET_KEY", "mps-secret"
+    )
+
+    client = MPSServiceKeyClient()
+
+    assert await client.report_platform_usage(
+        organization_id=42,
+        duration_seconds=87.0,
+        workflow_run_id=123,
+        metadata={"source": "workflow_run_completion"},
+    ) == {"metered": True}
+    assert calls == [
+        (
+            "POST",
+            f"{client.base_url}/api/v1/billing/accounts/42/platform-usage",
+            {
+                "duration_seconds": 87.0,
+                "workflow_run_id": 123,
+                "metadata": {"source": "workflow_run_completion"},
+            },
+            {
+                "Content-Type": "application/json",
+                "X-Secret-Key": "mps-secret",
+                "X-Organization-Id": "42",
+            },
+        )
+    ]