Feature-Flag: org/project feature flags with DB

backend/app/alembic/versions/057_create_feature_flag_table.py

@@ -0,0 +1,156 @@
+"""create feature flag table
+
+Revision ID: 057
+Revises: 056
+Create Date: 2026-04-22 12:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+from app.core.feature_flags.constants import FeatureFlag as FeatureFlagKeyEnum
+
+# revision identifiers, used by Alembic.
+revision = "057"
+down_revision = "056"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    op.create_table(
+        "feature_flag",
+        sa.Column(
+            "id",
+            sa.Integer(),
+            nullable=False,
+            comment="Unique identifier for feature flag",
+        ),
+        sa.Column(
+            "key",
+            sa.Enum("ASSESSMENT", name="featureflagkey"),
+            nullable=False,
+            comment="Feature flag key",
+        ),
+        sa.Column(
+            "organization_id",
+            sa.Integer(),
+            nullable=False,
+            comment="Organization scope for this feature flag",
+        ),
+        sa.Column(
+            "project_id",
+            sa.Integer(),
+            nullable=False,
+            comment="Project scope for this feature flag",
+        ),
+        sa.Column(
+            "enabled",
+            sa.Boolean(),
+            nullable=False,
+            comment="Whether the feature flag is enabled",
+        ),
+        sa.Column(
+            "inserted_at",
+            sa.DateTime(),
+            nullable=False,
+            comment="Timestamp when the flag row was created",
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(),
+            nullable=False,
+            comment="Timestamp when the flag row was last updated",
+        ),
+        sa.ForeignKeyConstraint(
+            ["organization_id"],
+            ["organization.id"],
+            name="fk_feature_flag_organization_id",
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["project_id"],
+            ["project.id"],
+            name="fk_feature_flag_project_id",
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        op.f("ix_feature_flag_key"),
+        "feature_flag",
+        ["key"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_feature_flag_organization_id"),
+        "feature_flag",
+        ["organization_id"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_feature_flag_project_id"),
+        "feature_flag",
+        ["project_id"],
+        unique=False,
+    )
+    op.create_index(
+        "uq_feature_flag_key_org_project",
+        "feature_flag",
+        ["key", "organization_id", "project_id"],
+        unique=True,
+    )
+
+    op.execute(
+        sa.text(
+            f"""
+            INSERT INTO feature_flag
+                (key, organization_id, project_id, enabled, inserted_at, updated_at)
+            SELECT '{FeatureFlagKeyEnum.ASSESSMENT.value}'::featureflagkey,
+                   p.organization_id, p.id, FALSE, NOW(), NOW()
+            FROM project p
+            """
+        )
+    )
+
+    op.execute(
+        sa.text(
+            f"""
+            CREATE OR REPLACE FUNCTION seed_default_feature_flag()
+            RETURNS trigger
+            LANGUAGE plpgsql
+            AS $$
+            BEGIN
+                INSERT INTO feature_flag
+                    (key, organization_id, project_id, enabled, inserted_at, updated_at)
+                VALUES
+                    ('{FeatureFlagKeyEnum.ASSESSMENT.value}'::featureflagkey,
+                     NEW.organization_id, NEW.id, FALSE, NOW(), NOW());
+                RETURN NEW;
+            END;
+            $$;
+            """
+        )
+    )
+    op.execute(
+        sa.text(
+            """
+            CREATE TRIGGER trg_seed_default_feature_flag
+            AFTER INSERT ON project
+            FOR EACH ROW
+            EXECUTE FUNCTION seed_default_feature_flag();
+            """
+        )
+    )
+
+
+def downgrade():
+    op.execute("DROP TRIGGER IF EXISTS trg_seed_default_feature_flag ON project")
+    op.execute("DROP FUNCTION IF EXISTS seed_default_feature_flag()")
+    op.drop_index("uq_feature_flag_key_org_project", table_name="feature_flag")
+    op.drop_index(op.f("ix_feature_flag_project_id"), table_name="feature_flag")
+    op.drop_index(op.f("ix_feature_flag_organization_id"), table_name="feature_flag")
+    op.drop_index(op.f("ix_feature_flag_key"), table_name="feature_flag")
+    op.drop_table("feature_flag")
+    sa.Enum(name="featureflagkey").drop(op.get_bind())

backend/app/api/docs/features/create_flag.md

@@ -0,0 +1,16 @@
+Create a project-scoped feature flag. Superuser only.
+
+Required payload fields:
+- `key`
+- `organization_id`
+- `project_id`
+- `enabled`
+- Currently supported key(s): `ASSESSMENT`.
+
+Validation:
+- `organization_id` must exist.
+- `project_id` must exist and belong to `organization_id`.
+
+Behavior:
+- A flag is unique by (`key`, `organization_id`, `project_id`).
+- Returns `409` if the same flag already exists.

backend/app/api/docs/features/delete_flag.md

@@ -0,0 +1,14 @@
+Delete a project-scoped feature flag. Superuser only.
+
+Required payload fields:
+- `key`
+- `organization_id`
+- `project_id`
+
+Validation:
+- `organization_id` must exist.
+- `project_id` must exist and belong to `organization_id`.
+
+Returns:
+- `{"deleted": true}` on success.
+- `404` if the target flag does not exist.

backend/app/api/docs/features/list_flags.md

@@ -0,0 +1,12 @@
+List feature flag records. Superuser only.
+
+Query parameters are optional:
+- `key`
+- `organization_id`
+- `project_id`
+
+`key` matches stored feature flag values (currently `ASSESSMENT`).
+
+Validation:
+- When `project_id` is provided, `organization_id` is required.
+- If both are provided, `project_id` must belong to `organization_id`.

backend/app/api/docs/features/update_flag.md

@@ -0,0 +1,15 @@
+Update a project-scoped feature flag. Superuser only.
+
+Required payload fields:
+- `key`
+- `organization_id`
+- `project_id`
+- `enabled`
+- Currently supported key(s): `ASSESSMENT`.
+
+Validation:
+- `organization_id` must exist.
+- `project_id` must exist and belong to `organization_id`.
+
+Returns:
+- `404` if the target flag does not exist.

backend/app/api/docs/users/get_me.md

@@ -0,0 +1,5 @@
+Return the current authenticated user's profile.
+
+All standard user profile fields are always returned.
+
+`features` is returned only when both organization and project are available for the user; otherwise it is `[]`.

backend/app/api/main.py

@@ -2,6 +2,7 @@
 
 from app.api.routes import (
     api_keys,
+    assessment as assessment_routes,
     assistants,
     auth,
     collection_job,
@@ -12,6 +13,7 @@
     doc_transformation_job,
     documents,
     evaluations,
+    features,
     fine_tuning,
     languages,
     llm,
@@ -30,27 +32,29 @@
     users,
     utils,
 )
-from app.api.routes import (
-    assessment as assessment_routes,
-)
 from app.core.config import settings
 
 api_router = APIRouter()
 api_router.include_router(api_keys.router)
+api_router.include_router(assessment_routes.router)
 api_router.include_router(assistants.router)
-api_router.include_router(collections.router)
+api_router.include_router(auth.router)
 api_router.include_router(collection_job.router)
+api_router.include_router(collections.router)
 api_router.include_router(config.router)
 api_router.include_router(credentials.router)
 api_router.include_router(cron.router)
 api_router.include_router(doc_transformation_job.router)
 api_router.include_router(documents.router)
-api_router.include_router(auth.router)
 api_router.include_router(evaluations.router)
+api_router.include_router(features.router)
+api_router.include_router(fine_tuning.router)
 api_router.include_router(languages.router)
 api_router.include_router(llm.router)
 api_router.include_router(llm_chain.router)
 api_router.include_router(login.router)
+api_router.include_router(model_config.router)
+api_router.include_router(model_evaluation.router)
 api_router.include_router(onboarding.router)
 api_router.include_router(openai_conversation.router)
 api_router.include_router(organization.router)
@@ -60,10 +64,6 @@
 api_router.include_router(user_project.router)
 api_router.include_router(users.router)
 api_router.include_router(utils.router)
-api_router.include_router(fine_tuning.router)
-api_router.include_router(model_evaluation.router)
-api_router.include_router(model_config.router)
-api_router.include_router(assessment_routes.router)
 
 if settings.ENVIRONMENT in ["development", "testing"]:
     api_router.include_router(private.router)

backend/app/api/permissions.py

@@ -1,13 +1,14 @@
-from enum import Enum
-from typing import Annotated
-from fastapi import Depends, HTTPException
+from enum import StrEnum
+
+from fastapi import HTTPException
 from sqlmodel import Session
 
-from app.models import AuthContext
 from app.api.deps import AuthContextDep, SessionDep
+from app.core.feature_flags import FeatureFlag
+from app.models import AuthContext
 
 
-class Permission(str, Enum):
+class Permission(StrEnum):
     """Permission types for authorization checks"""
 
     SUPERUSER = "require_superuser"
@@ -18,7 +19,7 @@ class Permission(str, Enum):
 def has_permission(
     auth_context: AuthContext,
     permission: Permission,
-    session: Session | None = None,
+    _session: Session | None = None,
 ) -> bool:
     """
     Check if the auth_context has the specified permission.
@@ -68,3 +69,40 @@ def permission_checker(
             )
 
     return permission_checker
+
+
+def require_feature(flag: FeatureFlag):
+    """Dependency factory that gates a route behind a feature flag.
+
+    Returns 403 when the flag is disabled for the caller's org/project,
+    so callers can explicitly handle feature access denial.
+
+    Usage::
+
+        router = APIRouter(
+            dependencies=[Depends(require_feature(FeatureFlag.ASSESSMENT))]
+        )
+    """
+
+    def _check_with_session(auth_context: AuthContextDep, session: SessionDep):
+        from app.core.feature_flags import is_enabled
+
+        org_id = auth_context.organization.id if auth_context.organization else None
+        project_id = auth_context.project.id if auth_context.project else None
+
+        if (
+            org_id is None
+            or project_id is None
+            or not is_enabled(
+                session=session,
+                flag=flag.value,
+                organization_id=org_id,
+                project_id=project_id,
+            )
+        ):
+            raise HTTPException(
+                status_code=403,
+                detail=f"Feature '{flag.value}' is not enabled for this org or project.",
+            )
+
+    return _check_with_session

backend/app/api/routes/assessment/__init__.py

@@ -1,10 +1,14 @@
-"""Main router for assessment API routes."""
-
-from fastapi import APIRouter
+from fastapi import APIRouter, Depends
 
+from app.api.permissions import require_feature
 from app.api.routes.assessment import assessments, datasets, runs
+from app.core.feature_flags import FeatureFlag
 
-router = APIRouter(prefix="/assessment", tags=["Assessment"])
+router = APIRouter(
+    prefix="/assessment",
+    tags=["Assessment"],
+    dependencies=[Depends(require_feature(FeatureFlag.ASSESSMENT))],
+)
 
 router.include_router(datasets.router)
 router.include_router(assessments.router)

backend/app/api/routes/cron.py

@@ -89,7 +89,7 @@ async def evaluation_cron_job(
                 f"[evaluation_cron_job] Assessment polling failed: {ae}",
                 exc_info=True,
             )
-            result["assessment_error"] = str(ae)
+            result["assessment_error"] = "Assessment polling failed"
 
         logger.info(
             f"[evaluation_cron_job] Completed: "