interloper-api 0.2.0__py3-none-any.whl

interloper_api/__init__.py

@@ -0,0 +1,3 @@
+from interloper_api.app import create_app
+
+__all__ = ["create_app"]

interloper_api/app.py

@@ -0,0 +1,100 @@
+"""FastAPI application factory for the interloper API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from interloper.catalog.base import Catalog
+from interloper_db import Store
+
+from interloper_api.dependencies import set_auth_config, set_catalog, set_smtp_config, set_store
+from interloper_api.routes import (
+    assets,
+    auth,
+    backfills,
+    destinations,
+    external,
+    jobs,
+    oauth,
+    organisations,
+    resources,
+    runs,
+    sources,
+    ws,
+)
+from interloper_api.routes import catalog as catalog_routes
+
+
+def create_app(
+    store: Store | None = None,
+    catalog: Catalog | None = None,
+    auth_config: Any | None = None,
+    smtp_config: Any | None = None,
+    cors_origins: list[str] | None = None,
+    **kwargs: Any,
+) -> FastAPI:
+    """Create the FastAPI application with all routes.
+
+    Args:
+        store: The ``Store`` instance for persistence.
+        catalog: Catalog instance.
+        auth_config: ``AuthConfig`` instance for authentication settings.
+        smtp_config: ``SmtpConfig`` instance for sending invitation emails.
+        cors_origins: Allowed CORS origins. Only needed in dev mode for direct
+            WebSocket connections that bypass the Vite proxy.
+        **kwargs: Additional kwargs forwarded to ``FastAPI()``.
+
+    Returns:
+        The configured FastAPI application.
+    """
+    app = FastAPI(title="Interloper API", lifespan=ws.realtime_lifespan, **kwargs)
+
+    if cors_origins:
+        app.add_middleware(
+            CORSMiddleware,  # type: ignore[arg-type]
+            allow_origins=cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    if store:
+        set_store(store)
+    if catalog:
+        set_catalog(catalog)
+    if auth_config:
+        set_auth_config(auth_config)
+    if smtp_config:
+        set_smtp_config(smtp_config)
+
+    api = APIRouter(prefix="/api")
+    api.include_router(auth.router, tags=["auth"])
+    api.include_router(organisations.router, tags=["organisations"])
+    api.include_router(catalog_routes.router, prefix="/catalog", tags=["catalog"])
+    api.include_router(resources.router, prefix="/resources", tags=["resources"])
+    api.include_router(sources.router, prefix="/sources", tags=["sources"])
+    api.include_router(destinations.router, prefix="/destinations", tags=["destinations"])
+    api.include_router(jobs.router, prefix="/jobs", tags=["jobs"])
+    api.include_router(runs.router, prefix="/runs", tags=["runs"])
+    api.include_router(backfills.router, prefix="/backfills", tags=["backfills"])
+    api.include_router(assets.router, prefix="/assets", tags=["assets"])
+    api.include_router(oauth.router, tags=["oauth"])
+    api.include_router(external.router, prefix="/external", tags=["external"])
+    api.include_router(ws.router, tags=["ws"])
+
+    try:
+        from interloper_api.routes import agent as agent_routes
+
+        api.include_router(agent_routes.router, prefix="/agent", tags=["agent"])
+    except ImportError:
+        pass
+
+    @api.get("/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    app.include_router(api)
+
+    return app

interloper_api/dependencies.py

@@ -0,0 +1,293 @@
+"""Shared FastAPI dependencies for store, catalog, auth, and RBAC."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from fastapi import Cookie, Depends, HTTPException
+from interloper.catalog.base import Catalog
+from interloper_db import Organisation, Profile, Store
+from interloper_db.models import Session as SessionModel
+
+_store: Store | None = None
+_catalog: Catalog | None = None
+_auth_config: Any | None = None
+_smtp_config: Any | None = None
+
+# Role hierarchy: admin > editor > viewer
+_ROLE_RANK = {"viewer": 0, "editor": 1, "admin": 2}
+
+
+def set_store(store: Store) -> None:
+    """Set the global store instance.
+
+    Args:
+        store: The Store to use for all API operations.
+    """
+    global _store  # noqa: PLW0603
+    _store = store
+
+
+def set_catalog(catalog: Catalog) -> None:
+    """Set the global catalog instance.
+
+    Args:
+        catalog: The Catalog instance.
+    """
+    global _catalog  # noqa: PLW0603
+    _catalog = catalog
+
+
+def set_auth_config(auth_config: Any) -> None:
+    """Set the global auth config.
+
+    Args:
+        auth_config: The AuthConfig instance.
+    """
+    global _auth_config  # noqa: PLW0603
+    _auth_config = auth_config
+
+
+def get_store() -> Store:
+    """Return the global store instance.
+
+    Returns:
+        The Store.
+
+    Raises:
+        RuntimeError: If the store has not been set.
+    """
+    if _store is None:
+        raise RuntimeError("Store not initialized. Call set_store() first.")
+    return _store
+
+
+def get_catalog() -> dict[str, Any]:
+    """Return the global catalog as a serialized dict.
+
+    Returns:
+        Mapping from component key to serialized definition.
+
+    Raises:
+        RuntimeError: If the catalog has not been set.
+    """
+    if _catalog is None:
+        raise RuntimeError("Catalog not initialized. Call set_catalog() first.")
+    return _catalog.dump()
+
+
+def get_auth_config() -> Any:
+    """Return the global auth config.
+
+    Returns:
+        The AuthConfig instance.
+
+    Raises:
+        RuntimeError: If the auth config has not been set.
+    """
+    if _auth_config is None:
+        raise RuntimeError("Auth config not initialized. Call set_auth_config() first.")
+    return _auth_config
+
+
+def set_smtp_config(smtp_config: Any) -> None:
+    """Set the global SMTP config.
+
+    Args:
+        smtp_config: The SmtpConfig instance.
+    """
+    global _smtp_config  # noqa: PLW0603
+    _smtp_config = smtp_config
+
+
+def get_smtp_config() -> Any:
+    """Return the global SMTP config.
+
+    Returns:
+        The SmtpConfig instance, or None if not configured.
+    """
+    return _smtp_config
+
+
+# -- Auth dependencies -------------------------------------------------------
+
+
+def get_current_user(
+    store: Store = Depends(get_store),
+    session_token: str | None = Cookie(default=None),
+) -> Profile:
+    """Resolve the current user from the session cookie.
+
+    Args:
+        store: The Store instance.
+        session_token: Session cookie value.
+
+    Returns:
+        The authenticated Profile.
+
+    Raises:
+        HTTPException: 401 if not authenticated or session invalid/expired.
+    """
+    if not session_token:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+
+    result = store.resolve_session(session_token)
+    if not result:
+        raise HTTPException(status_code=401, detail="Invalid or expired session")
+
+    profile, _ = result
+    return profile
+
+
+def get_session_context(
+    store: Store = Depends(get_store),
+    session_token: str | None = Cookie(default=None),
+) -> tuple[Profile, SessionModel]:
+    """Resolve user and session from the cookie.
+
+    Args:
+        store: The Store instance.
+        session_token: Session cookie value.
+
+    Returns:
+        ``(Profile, Session)`` tuple.
+
+    Raises:
+        HTTPException: 401 if not authenticated.
+    """
+    if not session_token:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+
+    result = store.resolve_session(session_token)
+    if not result:
+        raise HTTPException(status_code=401, detail="Invalid or expired session")
+
+    return result
+
+
+def get_current_org(
+    store: Store = Depends(get_store),
+    session_token: str | None = Cookie(default=None),
+) -> Organisation:
+    """Resolve the current organisation from the session.
+
+    Args:
+        store: The Store instance.
+        session_token: Session cookie value.
+
+    Returns:
+        The active Organisation.
+
+    Raises:
+        HTTPException: 400 if no organisation selected, 401 if not authenticated.
+    """
+    if not session_token:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+
+    result = store.resolve_session(session_token)
+    if not result:
+        raise HTTPException(status_code=401, detail="Invalid or expired session")
+
+    _, session_row = result
+    if not session_row.organisation_id:
+        raise HTTPException(status_code=400, detail="No organisation selected")
+
+    org = store.get_organisation(session_row.organisation_id)
+    if not org:
+        raise HTTPException(status_code=404, detail="Organisation not found")
+
+    return org
+
+
+def get_org_id(
+    org: Organisation = Depends(get_current_org),
+) -> UUID:
+    """Shorthand: return just the org UUID for route handlers.
+
+    Args:
+        org: The resolved Organisation.
+
+    Returns:
+        The organisation UUID.
+    """
+    return org.id  # type: ignore[return-value]
+
+
+# -- RBAC dependencies -------------------------------------------------------
+
+
+def _check_role(
+    minimum: str,
+    user: Profile,
+    org_id: UUID,
+    store: Store,
+) -> Profile:
+    """Verify the user has at least the required role in the org.
+
+    Args:
+        minimum: Minimum role required (``viewer``, ``editor``, ``admin``).
+        user: The authenticated user.
+        org_id: The active organisation UUID.
+        store: The Store instance.
+
+    Returns:
+        The authenticated Profile (pass-through for dependency chaining).
+
+    Raises:
+        HTTPException: 403 if insufficient permissions.
+    """
+    role = store.get_user_role(user.id, org_id)  # type: ignore[arg-type]
+    if role is None:
+        raise HTTPException(status_code=403, detail="Not a member of this organisation")
+    if _ROLE_RANK.get(role, -1) < _ROLE_RANK[minimum]:
+        raise HTTPException(status_code=403, detail=f"Requires {minimum} role or higher")
+    return user
+
+
+def require_viewer(
+    user: Profile = Depends(get_current_user),
+    org_id: UUID = Depends(get_org_id),
+    store: Store = Depends(get_store),
+) -> Profile:
+    """Require at least ``viewer`` role. Any org member passes.
+
+    Returns:
+        The authenticated Profile.
+
+    Raises:
+        HTTPException: 401/403 on auth or role failure.
+    """
+    return _check_role("viewer", user, org_id, store)
+
+
+def require_editor(
+    user: Profile = Depends(get_current_user),
+    org_id: UUID = Depends(get_org_id),
+    store: Store = Depends(get_store),
+) -> Profile:
+    """Require at least ``editor`` role.
+
+    Returns:
+        The authenticated Profile.
+
+    Raises:
+        HTTPException: 401/403 on auth or role failure.
+    """
+    return _check_role("editor", user, org_id, store)
+
+
+def require_admin(
+    user: Profile = Depends(get_current_user),
+    org_id: UUID = Depends(get_org_id),
+    store: Store = Depends(get_store),
+) -> Profile:
+    """Require ``admin`` role.
+
+    Returns:
+        The authenticated Profile.
+
+    Raises:
+        HTTPException: 401/403 on auth or role failure.
+    """
+    return _check_role("admin", user, org_id, store)

interloper_api/email.py

@@ -0,0 +1,79 @@
+"""SMTP email utilities for sending invitation emails."""
+
+from __future__ import annotations
+
+import logging
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def send_invite_email(
+    smtp_config: Any,
+    to: str,
+    org_name: str,
+    inviter_name: str,
+    invite_url: str,
+) -> None:
+    """Send an organisation invitation email via SMTP.
+
+    Args:
+        smtp_config: SmtpConfig instance with host, port, user, password, from_addr.
+        to: Recipient email address.
+        org_name: Name of the organisation.
+        inviter_name: Display name of the person who sent the invite.
+        invite_url: Full URL to accept the invitation.
+
+    Raises:
+        RuntimeError: If SMTP is not configured.
+        smtplib.SMTPException: If sending fails.
+    """
+    if not smtp_config.enabled:
+        raise RuntimeError("SMTP is not configured. Set smtp.host, smtp.user, and smtp.password.")
+
+    msg = MIMEMultipart("alternative")
+    msg["Subject"] = f"You've been invited to join {org_name} on Interloper"
+    msg["From"] = smtp_config.from_addr
+    msg["To"] = to
+
+    text = (
+        f"{inviter_name} has invited you to join the {org_name} organisation on Interloper.\n\n"
+        f"Click the link below to accept the invitation:\n{invite_url}\n\n"
+        "This invitation expires in 7 days."
+    )
+
+    html = f"""\
+<html>
+<body style="font-family: sans-serif; color: #333;">
+    <h2>You've been invited to join {org_name}</h2>
+    <p>{inviter_name} has invited you to join the <strong>{org_name}</strong> organisation on Interloper.</p>
+    <p>
+        <a href="{invite_url}"
+           style="display: inline-block; padding: 10px 20px; background: #2563eb;
+                  color: #fff; text-decoration: none; border-radius: 6px;">
+            Accept Invitation
+        </a>
+    </p>
+    <p style="color: #666; font-size: 0.875rem;">This invitation expires in 7 days.</p>
+</body>
+</html>"""
+
+    msg.attach(MIMEText(text, "plain"))
+    msg.attach(MIMEText(html, "html"))
+
+    logger.info("Sending invite email to %s", to)
+
+    if smtp_config.port == 465:
+        with smtplib.SMTP_SSL(smtp_config.host, smtp_config.port) as server:
+            server.login(smtp_config.user, smtp_config.password)
+            server.sendmail(smtp_config.from_addr, to, msg.as_string())
+    else:
+        with smtplib.SMTP(smtp_config.host, smtp_config.port) as server:
+            server.starttls()
+            server.login(smtp_config.user, smtp_config.password)
+            server.sendmail(smtp_config.from_addr, to, msg.as_string())
+
+    logger.info("Invite email sent to %s", to)

interloper_api/routes/agent.py

@@ -0,0 +1,229 @@
+"""Agent API: ADK-powered chat sessions with SSE streaming.
+
+Provides endpoints for creating agent chat sessions, sending messages,
+and streaming responses. The ADK Runner executes the interloper agent
+in-process, reusing the API's authenticated Store and catalog.
+
+Available when ``interloper-agent`` is installed.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Response
+from fastapi.responses import StreamingResponse
+from google.adk.apps import App
+from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService
+from google.adk.runners import Runner
+from google.adk.sessions.in_memory_session_service import InMemorySessionService
+from google.genai import types
+from interloper.catalog.base import Catalog
+from interloper_db import Profile, Store
+from pydantic import BaseModel
+
+from interloper_api.dependencies import get_catalog, get_org_id, get_store, require_editor, require_viewer
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+APP_NAME = "interloper_agent"
+
+# ---------------------------------------------------------------------------
+# Lazy runner singleton
+# ---------------------------------------------------------------------------
+
+_runner: Runner | None = None
+_session_service: InMemorySessionService | None = None
+
+
+def _get_session_service() -> InMemorySessionService:
+    """Return the shared session service, creating it on first call."""
+    global _session_service  # noqa: PLW0603
+    if _session_service is None:
+        _session_service = InMemorySessionService()
+    return _session_service
+
+
+def _get_runner(store: Store, catalog: Catalog) -> Runner:
+    """Return the shared Runner, creating it on first call.
+
+    On first call, injects the API's Store and catalog into the agent
+    context so that agent tools can access them.
+
+    Args:
+        store: The Store instance (from API dependencies).
+        catalog: The Catalog instance (from API dependencies).
+    """
+    global _runner  # noqa: PLW0603
+    if _runner is None:
+        from interloper_agent.agent import root_agent
+        from interloper_agent.context import set_catalog, set_store
+
+        if store is not None:
+            set_store(store)
+        if catalog is not None:
+            set_catalog(catalog)
+
+        app = App(name=APP_NAME, root_agent=root_agent)
+        _runner = Runner(
+            app=app,
+            session_service=_get_session_service(),
+            artifact_service=InMemoryArtifactService(),
+        )
+        logger.info("Agent runner initialized")
+    return _runner
+
+
+# ---------------------------------------------------------------------------
+# Request / response models
+# ---------------------------------------------------------------------------
+
+
+class ChatRequest(BaseModel):
+    """Request body for sending a chat message."""
+
+    message: str
+
+
+class SessionResponse(BaseModel):
+    """Response body for an agent session."""
+
+    id: str
+    user_id: str
+    app_name: str
+    state: dict[str, Any]
+    last_update_time: float
+    event_count: int
+
+
+def _session_to_response(session: Any) -> SessionResponse:
+    """Convert an ADK Session to a response model."""
+    return SessionResponse(
+        id=session.id,
+        user_id=session.user_id,
+        app_name=session.app_name,
+        state=session.state,
+        last_update_time=session.last_update_time,
+        event_count=len(session.events),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.post("/sessions")
+async def create_session(
+    user: Profile = Depends(require_editor),
+    org_id: UUID = Depends(get_org_id),
+    store: Store = Depends(get_store),
+    catalog: Catalog = Depends(get_catalog),
+) -> SessionResponse:
+    """Create a new agent chat session.
+
+    The authenticated user's ``org_id`` is injected into the ADK session
+    state so agent tools are scoped to the correct organisation.
+    """
+    _get_runner(store=store, catalog=catalog)
+    session_service = _get_session_service()
+    session = await session_service.create_session(
+        app_name=APP_NAME,
+        user_id=str(user.id),
+        state={"org_id": str(org_id)},
+    )
+    return _session_to_response(session)
+
+
+@router.get("/sessions")
+async def list_sessions(
+    user: Profile = Depends(require_viewer),
+) -> list[SessionResponse]:
+    """List all agent sessions for the current user."""
+    session_service = _get_session_service()
+    result = await session_service.list_sessions(
+        app_name=APP_NAME,
+        user_id=str(user.id),
+    )
+    sessions = result.sessions if hasattr(result, "sessions") else result
+    return [_session_to_response(s) for s in sessions]
+
+
+@router.get("/sessions/{session_id}")
+async def get_session(
+    session_id: str,
+    user: Profile = Depends(require_viewer),
+) -> Response:
+    """Get a session with its full event history.
+
+    Returns the session object including all events (messages and tool calls).
+    """
+    session_service = _get_session_service()
+    session = await session_service.get_session(
+        app_name=APP_NAME,
+        user_id=str(user.id),
+        session_id=session_id,
+    )
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return Response(
+        content=session.model_dump_json(exclude_none=True, by_alias=True),
+        media_type="application/json",
+    )
+
+
+@router.delete("/sessions/{session_id}")
+async def delete_session(
+    session_id: str,
+    user: Profile = Depends(require_editor),
+) -> dict[str, str]:
+    """Delete an agent session."""
+    session_service = _get_session_service()
+    session = await session_service.get_session(
+        app_name=APP_NAME,
+        user_id=str(user.id),
+        session_id=session_id,
+    )
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    await session_service.delete_session(
+        app_name=APP_NAME,
+        user_id=str(user.id),
+        session_id=session_id,
+    )
+    return {"status": "deleted"}
+
+
+@router.post("/sessions/{session_id}/chat")
+async def chat(
+    session_id: str,
+    body: ChatRequest,
+    user: Profile = Depends(require_editor),
+    store: Store = Depends(get_store),
+    catalog: Catalog = Depends(get_catalog),
+) -> StreamingResponse:
+    """Send a message and stream the agent's response as SSE.
+
+    Each SSE ``data`` line contains a JSON-serialized ADK Event.
+    Events with ``content.parts`` containing ``text`` are the agent's
+    text responses. Events with ``function_call`` or ``function_response``
+    parts represent tool invocations.
+    """
+    runner = _get_runner(store=store, catalog=catalog)
+    user_id = str(user.id)
+    message = types.Content(parts=[types.Part(text=body.message)], role="user")
+
+    async def event_stream() -> AsyncIterator[str]:
+        async for event in runner.run_async(
+            user_id=user_id,
+            session_id=session_id,
+            new_message=message,
+        ):
+            yield f"data: {event.model_dump_json(exclude_none=True, by_alias=True)}\n\n"
+
+    return StreamingResponse(event_stream(), media_type="text/event-stream")