kairo-code 0.1.0__py3-none-any.whl

kairo/backend/api/admin/stats.py

@@ -0,0 +1,125 @@
+import logging
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.core.database import get_db
+from backend.schemas.admin.stats import (
+    DailyCountResponse,
+    DailyTokensResponse,
+    OverviewStats,
+    PlanDistributionResponse,
+    RevenueStats,
+    TopUserAnalyticsResponse,
+    TopUserEntry,
+    UsageStatsEntry,
+    UserGrowthEntry,
+)
+from backend.services.admin.stats_service import AdminStatsService
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/stats", tags=["admin-stats"])
+
+
+@router.get("/overview", response_model=OverviewStats)
+async def get_overview(db: AsyncSession = Depends(get_db)):
+    svc = AdminStatsService(db)
+    data = await svc.get_overview()
+    return OverviewStats(**data)
+
+
+@router.get("/users", response_model=list[UserGrowthEntry])
+async def get_user_growth(
+    days: int = Query(30, ge=1, le=365),
+    db: AsyncSession = Depends(get_db),
+):
+    svc = AdminStatsService(db)
+    data = await svc.get_user_growth(days=days)
+    return [UserGrowthEntry(**entry) for entry in data]
+
+
+@router.get("/usage", response_model=list[UsageStatsEntry])
+async def get_usage_stats(
+    days: int = Query(30, ge=1, le=365),
+    db: AsyncSession = Depends(get_db),
+):
+    svc = AdminStatsService(db)
+    data = await svc.get_usage_stats(days=days)
+    return [UsageStatsEntry(**entry) for entry in data]
+
+
+@router.get("/revenue", response_model=RevenueStats)
+async def get_revenue_stats(db: AsyncSession = Depends(get_db)):
+    svc = AdminStatsService(db)
+    data = await svc.get_revenue_stats()
+    return RevenueStats(**data)
+
+
+@router.get("/top-users", response_model=list[TopUserEntry])
+async def get_top_users(
+    limit: int = Query(20, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+):
+    svc = AdminStatsService(db)
+    data = await svc.get_top_users(limit=limit)
+    return [TopUserEntry(**entry) for entry in data]
+
+
+# ------------------------------------------------------------------ #
+#  Analytics chart / table endpoints                                  #
+# ------------------------------------------------------------------ #
+
+
+@router.get("/signups", response_model=DailyCountResponse)
+async def get_signups(
+    days: int = Query(30, ge=1, le=365),
+    db: AsyncSession = Depends(get_db),
+):
+    """Daily signup counts for the past N days (zero-filled)."""
+    svc = AdminStatsService(db)
+    data = await svc.get_daily_signups(days=days)
+    return DailyCountResponse(data=data)
+
+
+@router.get("/active-users", response_model=DailyCountResponse)
+async def get_active_users(
+    days: int = Query(30, ge=1, le=365),
+    db: AsyncSession = Depends(get_db),
+):
+    """Daily active user counts (users with usage records) for the past N days."""
+    svc = AdminStatsService(db)
+    data = await svc.get_daily_active_users(days=days)
+    return DailyCountResponse(data=data)
+
+
+@router.get("/usage-over-time", response_model=DailyTokensResponse)
+async def get_usage_over_time(
+    days: int = Query(30, ge=1, le=365),
+    db: AsyncSession = Depends(get_db),
+):
+    """Daily total tokens used for the past N days (zero-filled)."""
+    svc = AdminStatsService(db)
+    data = await svc.get_usage_over_time(days=days)
+    return DailyTokensResponse(data=data)
+
+
+@router.get("/plan-distribution", response_model=PlanDistributionResponse)
+async def get_plan_distribution(
+    db: AsyncSession = Depends(get_db),
+):
+    """Current count of users per plan."""
+    svc = AdminStatsService(db)
+    data = await svc.get_plan_distribution()
+    return PlanDistributionResponse(data=data)
+
+
+@router.get("/top-users/analytics", response_model=TopUserAnalyticsResponse)
+async def get_top_users_analytics(
+    limit: int = Query(20, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+):
+    """Top N users by token usage with conversation and image counts."""
+    svc = AdminStatsService(db)
+    data = await svc.get_top_users_analytics(limit=limit)
+    return TopUserAnalyticsResponse(data=data)

kairo/backend/api/admin/system.py

@@ -0,0 +1,87 @@
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.core.admin_auth import require_role
+from backend.core.database import get_db
+from backend.models.user import User
+from backend.schemas.admin.system import (
+    ConfigEntry,
+    ConfigResponse,
+    FeatureFlagItem,
+    FeatureFlagResponse,
+    FeatureFlagUpdate,
+    HealthStatus,
+)
+from backend.services.admin.audit_service import AuditService
+from backend.services.admin.system_service import AdminSystemService
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/system", tags=["admin-system"])
+
+
+@router.get("/health", response_model=HealthStatus)
+async def get_health(db: AsyncSession = Depends(get_db)):
+    svc = AdminSystemService(db)
+    data = await svc.get_health()
+    return HealthStatus(**data)
+
+
+@router.get("/feature-flags", response_model=FeatureFlagResponse)
+async def get_feature_flags(db: AsyncSession = Depends(get_db)):
+    svc = AdminSystemService(db)
+    flags = await svc.get_feature_flags()
+    items = []
+    for f in flags:
+        items.append(FeatureFlagItem(
+            key=f.key,
+            enabled=f.enabled,
+            updated_by=f.updated_by,
+            updated_at=f.updated_at.isoformat() if f.updated_at else None,
+        ))
+    return FeatureFlagResponse(flags=items)
+
+
+@router.patch(
+    "/feature-flags/{key}",
+    dependencies=[Depends(require_role("superadmin"))],
+)
+async def toggle_feature_flag(
+    key: str,
+    body: FeatureFlagUpdate,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_role("superadmin")),
+):
+    svc = AdminSystemService(db)
+    flag = await svc.toggle_feature_flag(key, body.enabled, admin.id)
+    if not flag:
+        raise HTTPException(status_code=404, detail="Feature flag not found")
+
+    audit = AuditService(db)
+    ip = request.client.host if request.client else "unknown"
+    ua = request.headers.get("user-agent", "")
+    await audit.log(
+        admin_user_id=admin.id,
+        action="system.feature_flag_toggled",
+        target_type="feature_flag",
+        target_id=key,
+        details={"enabled": body.enabled, "reason": body.reason},
+        ip_address=ip,
+        user_agent=ua,
+    )
+    return FeatureFlagItem(
+        key=flag.key,
+        enabled=flag.enabled,
+        updated_by=flag.updated_by,
+        updated_at=flag.updated_at.isoformat() if flag.updated_at else None,
+    )
+
+
+@router.get("/config", response_model=ConfigResponse)
+async def get_config(db: AsyncSession = Depends(get_db)):
+    svc = AdminSystemService(db)
+    entries = await svc.get_config()
+    return ConfigResponse(config=[ConfigEntry(**e) for e in entries])

kairo/backend/api/admin/users.py

@@ -0,0 +1,279 @@
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.core.admin_auth import require_role
+from backend.core.database import get_db
+from backend.models.user import User
+from backend.schemas.admin.users import (
+    AdminUserDetailResponse,
+    AdminUserListItem,
+    PlanChangeRequest,
+    RoleChangeRequest,
+    StatusChangeRequest,
+)
+from backend.services.admin.audit_service import AuditService
+from backend.services.admin.user_service import AdminUserService
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/users", tags=["admin-users"])
+
+
+def _get_ip(request: Request) -> str:
+    return request.client.host if request.client else "unknown"
+
+
+def _get_ua(request: Request) -> str:
+    return request.headers.get("user-agent", "")
+
+
+@router.get("")
+async def list_users(
+    search: str | None = Query(None),
+    plan: str | None = Query(None),
+    status: str | None = Query(None),
+    cursor: str | None = Query(None),
+    limit: int = Query(25, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+):
+    svc = AdminUserService(db)
+    users = await svc.list_users(search=search, plan=plan, status=status, cursor=cursor, limit=limit + 1)
+    has_more = len(users) > limit
+    if has_more:
+        users = users[:limit]
+    items = [AdminUserListItem.model_validate(u) for u in users]
+    next_cursor = users[-1].id if has_more else None
+    return {"items": items, "next_cursor": next_cursor}
+
+
+@router.get("/{user_id}", response_model=AdminUserDetailResponse)
+async def get_user_detail(
+    user_id: str,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_role("admin")),
+):
+    svc = AdminUserService(db)
+    user = await svc.get_user_detail(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    # Audit the read
+    audit = AuditService(db)
+    await audit.log(
+        admin_user_id=admin.id,
+        action="user.detail_viewed",
+        target_type="user",
+        target_id=user_id,
+        ip_address=_get_ip(request),
+        user_agent=_get_ua(request),
+    )
+    return AdminUserDetailResponse.model_validate(user)
+
+
+@router.patch("/{user_id}/plan", response_model=AdminUserDetailResponse)
+async def change_user_plan(
+    user_id: str,
+    body: PlanChangeRequest,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_role("admin")),
+):
+    svc = AdminUserService(db)
+    old_user = await svc.get_user_detail(user_id)
+    if not old_user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    old_plan = old_user.plan
+    user = await svc.change_plan(user_id, body.plan)
+
+    audit = AuditService(db)
+    await audit.log(
+        admin_user_id=admin.id,
+        action="user.plan_changed",
+        target_type="user",
+        target_id=user_id,
+        details={"old_plan": old_plan, "new_plan": body.plan, "reason": body.reason},
+        ip_address=_get_ip(request),
+        user_agent=_get_ua(request),
+    )
+    return AdminUserDetailResponse.model_validate(user)
+
+
+@router.patch("/{user_id}/status", response_model=AdminUserDetailResponse)
+async def change_user_status(
+    user_id: str,
+    body: StatusChangeRequest,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_role("admin")),
+):
+    svc = AdminUserService(db)
+    old_user = await svc.get_user_detail(user_id)
+    if not old_user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    old_status = getattr(old_user, "status", "active")
+    user = await svc.change_status(user_id, body.status)
+
+    audit = AuditService(db)
+    await audit.log(
+        admin_user_id=admin.id,
+        action="user.status_changed",
+        target_type="user",
+        target_id=user_id,
+        details={"old_status": old_status, "new_status": body.status, "reason": body.reason},
+        ip_address=_get_ip(request),
+        user_agent=_get_ua(request),
+    )
+    return AdminUserDetailResponse.model_validate(user)
+
+
+@router.patch(
+    "/{user_id}/role",
+    response_model=AdminUserDetailResponse,
+    dependencies=[Depends(require_role("superadmin"))],
+)
+async def change_user_role(
+    user_id: str,
+    body: RoleChangeRequest,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_role("superadmin")),
+):
+    svc = AdminUserService(db)
+    old_user = await svc.get_user_detail(user_id)
+    if not old_user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    old_role = getattr(old_user, "role", "user")
+    user = await svc.change_role(user_id, body.role)
+
+    audit = AuditService(db)
+    await audit.log(
+        admin_user_id=admin.id,
+        action="user.role_changed",
+        target_type="user",
+        target_id=user_id,
+        details={"old_role": old_role, "new_role": body.role, "reason": body.reason},
+        ip_address=_get_ip(request),
+        user_agent=_get_ua(request),
+    )
+    return AdminUserDetailResponse.model_validate(user)
+
+
+@router.get("/{user_id}/usage")
+async def get_user_usage(
+    user_id: str,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_role("admin")),
+):
+    svc = AdminUserService(db)
+    user = await svc.get_user_detail(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    audit = AuditService(db)
+    await audit.log(
+        admin_user_id=admin.id,
+        action="user.usage_viewed",
+        target_type="user",
+        target_id=user_id,
+        ip_address=_get_ip(request),
+        user_agent=_get_ua(request),
+    )
+    return await svc.get_user_usage(user_id)
+
+
+@router.get("/{user_id}/conversations")
+async def get_user_conversations(
+    user_id: str,
+    request: Request,
+    cursor: str | None = Query(None),
+    limit: int = Query(50, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_role("admin")),
+):
+    svc = AdminUserService(db)
+    user = await svc.get_user_detail(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    audit = AuditService(db)
+    await audit.log(
+        admin_user_id=admin.id,
+        action="user.conversations_viewed",
+        target_type="user",
+        target_id=user_id,
+        ip_address=_get_ip(request),
+        user_agent=_get_ua(request),
+    )
+
+    conversations = await svc.get_user_conversations(user_id, cursor=cursor, limit=limit)
+    return [
+        {
+            "id": c.id,
+            "title": c.title,
+            "model": c.model,
+            "created_at": c.created_at,
+            "updated_at": c.updated_at,
+        }
+        for c in conversations
+    ]
+
+
+@router.get("/{user_id}/images")
+async def get_user_images(
+    user_id: str,
+    request: Request,
+    cursor: str | None = Query(None),
+    limit: int = Query(50, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_role("admin")),
+):
+    svc = AdminUserService(db)
+    user = await svc.get_user_detail(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    audit = AuditService(db)
+    await audit.log(
+        admin_user_id=admin.id,
+        action="user.images_viewed",
+        target_type="user",
+        target_id=user_id,
+        ip_address=_get_ip(request),
+        user_agent=_get_ua(request),
+    )
+
+    from backend.schemas.admin.content import AdminImageListItem
+
+    images = await svc.get_user_images(user_id, cursor=cursor, limit=limit)
+    return [AdminImageListItem.model_validate(img) for img in images]
+
+
+@router.get("/{user_id}/api-keys")
+async def get_user_api_keys(
+    user_id: str,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_role("admin")),
+):
+    svc = AdminUserService(db)
+    user = await svc.get_user_detail(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    audit = AuditService(db)
+    await audit.log(
+        admin_user_id=admin.id,
+        action="user.api_keys_viewed",
+        target_type="user",
+        target_id=user_id,
+        ip_address=_get_ip(request),
+        user_agent=_get_ua(request),
+    )
+    return await svc.get_user_api_keys(user_id)

kairo/backend/api/agents.py

@@ -0,0 +1,94 @@
+from datetime import datetime, UTC
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.config import settings
+from backend.core.api_key_auth import get_api_key_user
+from backend.core.database import get_db
+from backend.core.dependencies import get_current_user
+from backend.models.api_key import ApiKey
+from backend.models.user import User
+from backend.schemas.agent import (
+    AgentHeartbeatRequest,
+    AgentHeartbeatResponse,
+    AgentResponse,
+    RegisterAgentRequest,
+    UpdateAgentRequest,
+)
+from backend.services.agent_service import AgentService
+
+router = APIRouter(prefix="/agents", tags=["Agents"])
+
+
+@router.post("/", response_model=AgentResponse)
+async def register_agent(
+    req: RegisterAgentRequest,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not settings.FEATURE_KAIRO_AGENTS_ENABLED:
+        raise HTTPException(status_code=503, detail="Kairo Agents is coming soon.")
+    svc = AgentService(db)
+    agent = await svc.register(user.id, req)
+    return agent
+
+
+@router.get("/", response_model=list[AgentResponse])
+async def list_agents(
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not settings.FEATURE_KAIRO_AGENTS_ENABLED:
+        raise HTTPException(status_code=503, detail="Kairo Agents is coming soon.")
+    svc = AgentService(db)
+    agents = await svc.list_agents(user.id)
+    return agents
+
+
+@router.patch("/{agent_id}", response_model=AgentResponse)
+async def update_agent(
+    agent_id: str,
+    req: UpdateAgentRequest,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not settings.FEATURE_KAIRO_AGENTS_ENABLED:
+        raise HTTPException(status_code=503, detail="Kairo Agents is coming soon.")
+    svc = AgentService(db)
+    agent = await svc.update_agent(user.id, agent_id, req)
+    if not agent:
+        raise HTTPException(status_code=404, detail="Agent not found")
+    return agent
+
+
+@router.delete("/{agent_id}")
+async def delete_agent(
+    agent_id: str,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not settings.FEATURE_KAIRO_AGENTS_ENABLED:
+        raise HTTPException(status_code=503, detail="Kairo Agents is coming soon.")
+    svc = AgentService(db)
+    deleted = await svc.delete_agent(user.id, agent_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="Agent not found")
+    return {"deleted": True}
+
+
+@router.post("/heartbeat", response_model=AgentHeartbeatResponse)
+async def agent_heartbeat(
+    req: AgentHeartbeatRequest,
+    auth: tuple[User, ApiKey] = Depends(get_api_key_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Agent heartbeat — authenticated via API key, not JWT."""
+    if not settings.FEATURE_KAIRO_AGENTS_ENABLED:
+        raise HTTPException(status_code=503, detail="Kairo Agents is coming soon.")
+    user, _api_key = auth
+    svc = AgentService(db)
+    agent = await svc.heartbeat(req.agent_id, user.id, req.status)
+    if not agent:
+        raise HTTPException(status_code=404, detail="Agent not found or not owned by this key's user")
+    return AgentHeartbeatResponse(acknowledged=True, server_time=datetime.now(UTC))

kairo/backend/api/api_keys.py

@@ -0,0 +1,85 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.config import settings
+from backend.core.database import get_db
+from backend.core.dependencies import get_current_user
+from backend.models.user import User
+from backend.schemas.api_key import (
+    ApiKeyCreatedResponse,
+    ApiKeyResponse,
+    CreateApiKeyRequest,
+    RevokeApiKeyResponse,
+)
+from backend.services.api_key_service import ApiKeyService
+from backend.services.api_usage_service import ApiUsageService
+
+router = APIRouter(prefix="/api-keys", tags=["API Keys"])
+
+
+@router.post("/", response_model=ApiKeyCreatedResponse)
+async def create_api_key(
+    req: CreateApiKeyRequest,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not settings.FEATURE_KAIRO_API_ENABLED:
+        raise HTTPException(status_code=503, detail="Kairo API is coming soon.")
+    svc = ApiKeyService(db)
+    api_key, raw_key = await svc.create_key(user.id, req.name, req.expires_in_days)
+    return ApiKeyCreatedResponse(
+        id=api_key.id,
+        name=api_key.name,
+        key_prefix=api_key.key_prefix,
+        is_active=api_key.is_active,
+        last_used_at=api_key.last_used_at,
+        created_at=api_key.created_at,
+        expires_at=api_key.expires_at,
+        full_key=raw_key,
+    )
+
+
+@router.get("/", response_model=list[ApiKeyResponse])
+async def list_api_keys(
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not settings.FEATURE_KAIRO_API_ENABLED:
+        raise HTTPException(status_code=503, detail="Kairo API is coming soon.")
+    svc = ApiKeyService(db)
+    keys = await svc.list_keys(user.id)
+    return keys
+
+
+@router.delete("/{key_id}", response_model=RevokeApiKeyResponse)
+async def revoke_api_key(
+    key_id: str,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not settings.FEATURE_KAIRO_API_ENABLED:
+        raise HTTPException(status_code=503, detail="Kairo API is coming soon.")
+    svc = ApiKeyService(db)
+    revoked = await svc.revoke_key(user.id, key_id)
+    if not revoked:
+        raise HTTPException(status_code=404, detail="API key not found")
+    return RevokeApiKeyResponse(id=key_id, revoked=True)
+
+
+@router.get("/{key_id}/usage")
+async def get_key_usage(
+    key_id: str,
+    days: int = 30,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not settings.FEATURE_KAIRO_API_ENABLED:
+        raise HTTPException(status_code=503, detail="Kairo API is coming soon.")
+    # Verify key belongs to user
+    key_svc = ApiKeyService(db)
+    keys = await key_svc.list_keys(user.id)
+    if not any(k.id == key_id for k in keys):
+        raise HTTPException(status_code=404, detail="API key not found")
+    usage_svc = ApiUsageService(db)
+    history = await usage_svc.get_key_usage_summary(key_id, days)
+    return {"usage": history}