databricks-tellr-app 0.3.11.dev6__tar.gz → 0.3.11.dev8__tar.gz

{databricks_tellr_app-0.3.11.dev6 → databricks_tellr_app-0.3.11.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databricks-tellr-app
-Version: 0.3.11.dev6
+Version: 0.3.11.dev8
 Summary: Tellr application package for Databricks Apps
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{databricks_tellr_app-0.3.11.dev6 → databricks_tellr_app-0.3.11.dev8}/databricks_tellr_app.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databricks-tellr-app
-Version: 0.3.11.dev6
+Version: 0.3.11.dev8
 Summary: Tellr application package for Databricks Apps
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{databricks_tellr_app-0.3.11.dev6 → databricks_tellr_app-0.3.11.dev8}/databricks_tellr_app.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ setup.py
 ./src/api/middleware/request_logging.py
 ./src/api/routes/__init__.py
 ./src/api/routes/admin.py
+./src/api/routes/admin_usage.py
 ./src/api/routes/agent_config.py
 ./src/api/routes/chat.py
 ./src/api/routes/deck_contributors.py
@@ -51,6 +52,8 @@ setup.py
 ./src/api/services/job_queue.py
 ./src/api/services/session_manager.py
 ./src/api/services/session_naming.py
+./src/api/services/usage_events.py
+./src/api/services/usage_service.py
 ./src/api/utils/__init__.py
 ./src/api/utils/validation.py
 ./src/core/__init__.py
@@ -86,6 +89,7 @@ setup.py
 ./src/database/models/session.py
 ./src/database/models/slide_deck_prompt.py
 ./src/database/models/slide_style_library.py
+./src/database/models/usage_event.py
 ./src/database/models/user_preference.py
 ./src/domain/__init__.py
 ./src/domain/slide.py
@@ -153,6 +157,7 @@ src/api/middleware/__init__.py
 src/api/middleware/request_logging.py
 src/api/routes/__init__.py
 src/api/routes/admin.py
+src/api/routes/admin_usage.py
 src/api/routes/agent_config.py
 src/api/routes/chat.py
 src/api/routes/deck_contributors.py
@@ -190,6 +195,8 @@ src/api/services/feedback_service.py
 src/api/services/job_queue.py
 src/api/services/session_manager.py
 src/api/services/session_naming.py
+src/api/services/usage_events.py
+src/api/services/usage_service.py
 src/api/utils/__init__.py
 src/api/utils/validation.py
 src/core/__init__.py
@@ -225,6 +232,7 @@ src/database/models/request_log.py
 src/database/models/session.py
 src/database/models/slide_deck_prompt.py
 src/database/models/slide_style_library.py
+src/database/models/usage_event.py
 src/database/models/user_preference.py
 src/domain/__init__.py
 src/domain/slide.py

{databricks_tellr_app-0.3.11.dev6 → databricks_tellr_app-0.3.11.dev8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "databricks-tellr-app"
-version = "0.3.11.dev6"
+version = "0.3.11.dev8"
 description = "Tellr application package for Databricks Apps"
 readme = "README.md"
 requires-python = ">=3.10"

{databricks_tellr_app-0.3.11.dev6 → databricks_tellr_app-0.3.11.dev8}/src/api/main.py

@@ -16,7 +16,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 
-from src.api.routes import admin, agent_config, chat, export, feedback, images, profiles, sessions, slides, tools, tour, verification, version, google_slides, setup, local_version
+from src.api.routes import admin, admin_usage, agent_config, chat, export, feedback, images, profiles, sessions, slides, tools, tour, verification, version, google_slides, setup, local_version
 from src.api.routes.deck_contributors import router as deck_contributors_router
 from src.core.databricks_client import get_or_create_user_client, set_user_client
 from src.core.user_context import get_current_user as get_ctx_user, set_current_user
@@ -381,6 +381,14 @@ async def user_auth_middleware(request: Request, call_next):
     )
     set_permission_context(permission_ctx)
 
+    # Record login usage-event (visit-deduped, non-blocking, all envs)
+    if user_name:
+        try:
+            from src.api.services.usage_events import record_login
+            record_login(user_name)
+        except Exception as e:
+            logger.debug(f"Failed to record login usage event: {e}")
+
     # Record user login for local identity table (non-blocking)
     if user_id and user_name and IS_PRODUCTION:
         try:
@@ -411,6 +419,7 @@ app.add_middleware(RequestLoggingMiddleware)
 
 # Include API routers
 app.include_router(admin.router)
+app.include_router(admin_usage.router)
 app.include_router(agent_config.router)
 app.include_router(chat.router)
 app.include_router(feedback.router)

databricks_tellr_app-0.3.11.dev8/src/api/routes/admin_usage.py

@@ -0,0 +1,69 @@
+"""Admin usage-analytics endpoints (ungated, like the rest of /admin)."""
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy.orm import Session
+
+from src.api.services.usage_service import ALLOWED_WINDOWS, UsageService
+from src.core.database import get_db
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/admin/usage", tags=["admin-usage"])
+
+
+def _validated_days(days: int) -> int:
+    if days not in ALLOWED_WINDOWS:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"days must be one of {sorted(ALLOWED_WINDOWS)}",
+        )
+    return days
+
+
+def _handle(callable_, *args, **kwargs):
+    try:
+        return callable_(*args, **kwargs)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Usage analytics error: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to compute usage analytics",
+        )
+
+
+@router.get("/summary")
+def get_summary(days: int = Query(default=7), db: Session = Depends(get_db)):
+    days = _validated_days(days)
+    return _handle(UsageService().get_summary, db, days=days)
+
+
+@router.get("/daily")
+def get_daily(days: int = Query(default=7), db: Session = Depends(get_db)):
+    days = _validated_days(days)
+    return _handle(UsageService().get_daily, db, days=days)
+
+
+@router.get("/top-users")
+def get_top_users(days: int = Query(default=7), db: Session = Depends(get_db)):
+    days = _validated_days(days)
+    return _handle(UsageService().get_top_users, db, days=days)
+
+
+@router.get("/funnel")
+def get_funnel(days: int = Query(default=7), db: Session = Depends(get_db)):
+    days = _validated_days(days)
+    return _handle(UsageService().get_funnel, db, days=days)
+
+
+@router.get("/retention")
+def get_retention(db: Session = Depends(get_db)):
+    return _handle(UsageService().get_retention, db)
+
+
+@router.get("/heatmap")
+def get_heatmap(days: int = Query(default=7), db: Session = Depends(get_db)):
+    days = _validated_days(days)
+    return _handle(UsageService().get_heatmap, db, days=days)

{databricks_tellr_app-0.3.11.dev6 → databricks_tellr_app-0.3.11.dev8}/src/api/routes/feedback.py

@@ -88,6 +88,33 @@ def get_stats_report(weeks: int = Query(default=12, ge=1, le=52), db: Session =
         )
 
 
+@router.get("/list")
+def list_feedback(
+    weeks: int = Query(default=12, ge=1, le=52),
+    category: str | None = Query(default=None),
+    severity: str | None = Query(default=None),
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=20, ge=1, le=100),
+    db: Session = Depends(get_db),
+):
+    try:
+        service = FeedbackService()
+        return service.list_feedback(
+            db=db,
+            weeks=weeks,
+            category=category,
+            severity=severity,
+            page=page,
+            page_size=page_size,
+        )
+    except Exception as e:
+        logger.error(f"Feedback list error: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to list feedback",
+        )
+
+
 @router.get("/report/summary")
 def get_feedback_summary(weeks: int = Query(default=4, ge=1, le=52), db: Session = Depends(get_db)):
     try:

{databricks_tellr_app-0.3.11.dev6 → databricks_tellr_app-0.3.11.dev8}/src/api/routes/sessions.py

@@ -25,6 +25,7 @@ from src.api.services.session_manager import (
     SessionNotFoundError,
     get_session_manager,
 )
+from src.api.services.usage_events import record_deck_retrieved
 from src.core.database import get_db, get_db_session
 from src.core.permission_context import get_permission_context
 from src.core.user_context import get_current_user
@@ -467,6 +468,10 @@ async def get_session(session_id: str, db: Session = Depends(get_db)):
         # Check permission
         permission = _require_session_access(session, db, PermissionLevel.CAN_VIEW)
 
+        # Record deck-open usage event (deduped per user+deck, non-blocking)
+        if current_user:
+            record_deck_retrieved(current_user, session.get("id"))
+
         # Only the session creator sees chat messages — conversations are private
         is_creator = session.get("created_by") == current_user
         messages = []

{databricks_tellr_app-0.3.11.dev6 → databricks_tellr_app-0.3.11.dev8}/src/api/services/feedback_service.py

@@ -215,6 +215,49 @@ class FeedbackService:
             "usage": usage,
         }
 
+    def list_feedback(
+        self,
+        db: Session,
+        weeks: int = 12,
+        category: str | None = None,
+        severity: str | None = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> Dict[str, Any]:
+        """Paginated raw feedback conversations, newest first. Anonymous."""
+        cutoff = datetime.utcnow() - timedelta(weeks=weeks)
+        query = db.query(FeedbackConversation).filter(
+            FeedbackConversation.created_at >= cutoff
+        )
+        if category:
+            query = query.filter(FeedbackConversation.category == category)
+        if severity:
+            query = query.filter(FeedbackConversation.severity == severity)
+
+        total = query.count()
+        items = (
+            query.order_by(FeedbackConversation.created_at.desc())
+            .offset((page - 1) * page_size)
+            .limit(page_size)
+            .all()
+        )
+        return {
+            "items": [
+                {
+                    "id": item.id,
+                    "created_at": item.created_at.isoformat(),
+                    "category": item.category,
+                    "severity": item.severity,
+                    "summary": item.summary,
+                    "raw_conversation": item.raw_conversation,
+                }
+                for item in items
+            ],
+            "total": total,
+            "page": page,
+            "page_size": page_size,
+        }
+
     def get_feedback_summary(self, db: Session, weeks: int = 4) -> Dict[str, Any]:
         """Generate an AI summary of feedback conversations."""
         cutoff = datetime.utcnow() - timedelta(weeks=weeks)

{databricks_tellr_app-0.3.11.dev6 → databricks_tellr_app-0.3.11.dev8}/src/api/services/session_manager.py

@@ -689,6 +689,17 @@ class SessionManager:
                 db.add(deck)
                 db.flush()
 
+                # Record deck-created usage event (non-blocking)
+                try:
+                    from src.api.services.usage_events import record_deck_created
+                    from src.core.user_context import get_current_user as _get_user
+
+                    record_deck_created(
+                        modified_by or _get_user(), deck_owner.id
+                    )
+                except Exception:
+                    logger.debug("Failed to record deck_created event", exc_info=True)
+
             # Update activity on both the requesting session and the deck owner
             session.last_activity = datetime.utcnow()
             if session.id != deck_owner.id:
@@ -1781,6 +1792,13 @@ class SessionManager:
     def cleanup_expired_sessions(self) -> int:
         """Delete sessions that have exceeded TTL.
 
+        WARNING: user_sessions is the app's durable usage history. This
+        method is intentionally NOT scheduled anywhere — it is only
+        reachable via the manual POST /api/sessions/cleanup endpoint.
+        Do not wire it to a scheduler; doing so would destroy the
+        history that the /admin usage dashboard's pre-event-log
+        aggregations rely on.
+
         Returns:
             Number of sessions deleted
         """

databricks_tellr_app-0.3.11.dev8/src/api/services/usage_events.py

@@ -0,0 +1,117 @@
+"""Fire-and-forget usage-event recording with in-process dedup.
+
+Mirrors the request_logs middleware pattern: writes happen on an executor
+thread (or inline when already off the event loop) and never raise.
+
+Dedup semantics (per spec):
+- ``login``: one event per "visit" — the first authenticated request after
+  >= 30 minutes without any authenticated request (sliding window: every
+  request refreshes the timer, so continuous activity never re-emits).
+- ``deck_retrieved``: one event per (username, session_id) per 30-minute window.
+- ``deck_created``: never deduped.
+
+Caches are per-process; a restart may produce occasional extra login
+events, which is acceptable.
+"""
+
+import asyncio
+import logging
+import time
+
+from src.database.models.usage_event import (
+    EVENT_DECK_CREATED,
+    EVENT_DECK_RETRIEVED,
+    EVENT_LOGIN,
+)
+
+logger = logging.getLogger(__name__)
+
+_DEDUP_WINDOW_SECONDS = 30 * 60
+
+_login_cache: dict[str, float] = {}
+_retrieval_cache: dict[tuple[str, str], float] = {}
+
+
+def reset_dedup_caches() -> None:
+    """Clear dedup caches (test helper)."""
+    _login_cache.clear()
+    _retrieval_cache.clear()
+
+
+def _write_event(username: str, event_type: str, session_id) -> None:
+    """Synchronously insert one usage event. Never raises."""
+    try:
+        from src.core.database import get_session_local
+        from src.database.models.usage_event import UsageEvent
+
+        session_factory = get_session_local()
+        db = session_factory()
+        try:
+            db.add(
+                UsageEvent(
+                    username=username,
+                    event_type=event_type,
+                    session_id=session_id,
+                )
+            )
+            db.commit()
+        except Exception:
+            logger.debug("Failed to write usage event", exc_info=True)
+            db.rollback()
+        finally:
+            db.close()
+    except Exception:
+        logger.debug("Failed to write usage event", exc_info=True)
+
+
+def _submit(username: str, event_type: str, session_id) -> None:
+    """Dispatch a write without blocking the caller.
+
+    On the event loop -> run_in_executor; in a worker thread (no running
+    loop) -> write inline, which is already off the loop.
+    """
+    try:
+        loop = asyncio.get_running_loop()
+        loop.run_in_executor(None, _write_event, username, event_type, session_id)
+    except RuntimeError:
+        _write_event(username, event_type, session_id)
+    except Exception:
+        logger.debug("Failed to submit usage event", exc_info=True)
+
+
+def record_login(username) -> None:
+    """Record a login "visit": the first authenticated request after >=30
+    minutes without any authenticated request (sliding window).
+
+    Every call refreshes the cached timestamp, so continuous activity keeps
+    the window sliding and emits no further events until the user has been
+    inactive for a full window.
+    """
+    if not username:
+        return
+    now = time.monotonic()
+    last = _login_cache.get(username)
+    _login_cache[username] = now
+    if last is not None and (now - last) < _DEDUP_WINDOW_SECONDS:
+        return
+    _submit(username, EVENT_LOGIN, None)
+
+
+def record_deck_created(username, session_id) -> None:
+    """Record a deck creation. Never deduped."""
+    if not username:
+        return
+    _submit(username, EVENT_DECK_CREATED, session_id)
+
+
+def record_deck_retrieved(username, session_id) -> None:
+    """Record a deck open, deduped per (user, deck) per 30-minute window."""
+    if not username:
+        return
+    key = (username, str(session_id))
+    now = time.monotonic()
+    last = _retrieval_cache.get(key)
+    if last is not None and (now - last) < _DEDUP_WINDOW_SECONDS:
+        return
+    _retrieval_cache[key] = now
+    _submit(username, EVENT_DECK_RETRIEVED, session_id)