contentgrid-assistant-api 0.0.2__py3-none-any.whl

_version.txt

@@ -0,0 +1 @@
+0.0.2

contentgrid_assistant_api/app.py

@@ -0,0 +1,131 @@
+import logging
+from typing import List
+from fastapi import Depends, FastAPI, status, Request
+from fastapi.middleware.cors import CORSMiddleware
+from openai import APIError
+from contentgrid_extension_helpers.middleware.exception_middleware import catch_exceptions_middleware
+from contentgrid_extension_helpers.responses.hal import FastAPIHALResponse, FastAPIHALCollection, HALLink, HALLinkFor
+from contentgrid_extension_helpers.logging import setup_json_logging
+from contentgrid_extension_helpers.problem_response import ProblemResponse
+
+from contentgrid_assistant_api.routers.agent_home import generate_agent_home_router
+from contentgrid_assistant_api.config import AssistantExtensionConfig, DatabaseConfig
+from contentgrid_assistant_api.types.agents import Agent, AgentHomeResponse
+
+
+class ContentGridAssistantAPI(FastAPI):
+    """Specialized FastAPI application for a ContentGrid Assistant"""
+    
+    def __init__(self, 
+                 extension_config: AssistantExtensionConfig | None = None, 
+                 database_config: DatabaseConfig | None = None, 
+                 agents: List[Agent] = [],
+                 *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.extension_config = extension_config or AssistantExtensionConfig()
+        self.database_config = database_config or DatabaseConfig()
+        
+        self._setup_logging()
+        if not self.extension_config.production:
+            self._setup_cors()
+        self._setup_hal_response()
+        
+        self._register_agent_routers(agents)
+        self._register_endpoints(agents)
+        self._register_middleware()
+    
+    @property
+    def _server_prefix(self) -> str:
+        path_prefix = self.extension_config.extension_path_prefix
+        if path_prefix:
+            if path_prefix.startswith("/"):
+                return path_prefix
+            else:
+                return f"/{path_prefix}"
+        else:
+            return ""
+    
+    def _format_problem_type(self, type: str) -> str:
+        """Format problem type URL using configured base URL"""
+        return f"{self.extension_config.problem_type_base_url}/{type}"
+    
+    def _setup_logging(self):
+        """Configure JSON logging for production environments"""
+        if self.extension_config.production:
+            setup_json_logging()
+    
+    def _setup_cors(self):
+        """Configure CORS middleware"""
+        self.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+    
+    def _setup_hal_response(self):
+        """Initialize HAL response configuration"""
+        FastAPIHALResponse.init_app(self)
+        FastAPIHALResponse.add_server_url(
+            self.extension_config.server_url or f"http://localhost:{self.extension_config.server_port or 8000}"
+        )
+    
+    def _register_agent_routers(self, agents : List[Agent]):
+        """Register API routers with authentication"""
+        for agent in agents:
+            self.include_router(
+                generate_agent_home_router(agent, self.extension_config, self.database_config),
+                prefix=f"{self.extension_config.extension_path_prefix if self.extension_config.extension_path_prefix else ''}/{agent.name}",
+                tags=[agent.name],
+                dependencies=[Depends(agent.get_current_user_override)]
+            )
+    
+    def _register_endpoints(self, agents : List[Agent]):
+        """Register root and health check endpoints"""
+        
+        @self.get(f"{self._server_prefix}/health")
+        def health_check():
+            return "ok"
+        
+        @self.get(f"{self._server_prefix}/", response_model=FastAPIHALCollection, response_model_exclude_unset=True)
+        def get_server_resources():
+            return FastAPIHALCollection(
+                _embedded={
+                    "agents" : [
+                        AgentHomeResponse(**agent.model_dump(), tags=[agent.name]) for agent in agents
+                    ] 
+                },
+                _links={
+                    "self": HALLinkFor(endpoint_function_name="get_server_resources"),
+                }
+            )
+    
+    def _register_middleware(self):
+        """Register custom middleware for exception handling"""
+        self.middleware("http")(self._create_openai_exception_middleware())
+        self.middleware("http")(catch_exceptions_middleware)
+    
+    def _create_openai_exception_middleware(self):
+        """Create OpenAI exception middleware with access to config"""
+        async def catch_openai_exceptions_middleware(request: Request, call_next):
+            """Handle OpenAI API exceptions and convert to problem responses"""
+            try:
+                return await call_next(request)
+            except APIError as e:
+                logging.exception(f"OpenAI error: {str(e)}", exc_info=True, stack_info=True)
+                if e.code == "unsupported_file":
+                    return ProblemResponse(
+                        title="File not supported",
+                        problem_type=self._format_problem_type("unsupported-file"),
+                        detail="Provided file extension is not supported.",
+                        status=status.HTTP_400_BAD_REQUEST
+                    )
+                else:
+                    return ProblemResponse(
+                        title="OpenAI error",
+                        problem_type=self._format_problem_type("openai-error"),
+                        detail="An unexpected OpenAI error occured.",
+                        status=status.HTTP_500_INTERNAL_SERVER_ERROR
+                    )
+        return catch_openai_exceptions_middleware

contentgrid_assistant_api/config.py

@@ -0,0 +1,55 @@
+from pydantic_settings import BaseSettings
+from pydantic import Field, ConfigDict
+from pydantic import computed_field
+import logging
+import urllib
+
+class AssistantExtensionConfig(BaseSettings):
+    model_config = ConfigDict(extra="allow", env_file=[".env", ".env.secret"], env_file_encoding="utf-8")
+    
+    production : bool = False
+        
+    
+    server_port: int | None = 8000
+    server_url: str | None = Field("http://localhost:8000", serialization_alias="BACKEND_URL")
+    web_concurrency: int | None = 1
+    opening_message : str = "Hello, please introduce yourself and list your available tools and functionalities."
+    graph_recursion_limit: int = 100
+        
+    extension_path_prefix : str | None = None
+
+    routes_assistant_prefix : str = "/assistant"
+    routes_thread_prefix : str = "/threads"
+    routes_message_prefix : str = "/messages"
+    
+    problem_type_base_url : str = "https://api.contentgrid.com/problems/ml"
+
+class DatabaseConfig(BaseSettings):
+    model_config = ConfigDict(extra="allow", env_file=[".env", ".env.secret"], env_file_encoding="utf-8")
+    
+    pg_dbname: str = "assistant"
+    pg_user: str = "assistant"
+    pg_passwd: str = "assistant"
+    pg_host: str = "postgres"
+    pg_port: str = "5432"
+    pg_reinitialize: bool = False
+    use_sqlite_db: bool = False
+    
+    @computed_field # type: ignore
+    @property
+    def database_url(self) -> str:
+        if self.use_sqlite_db:
+            logging.info("Using SQLite database")
+            return "sqlite:///sqlite.db"
+        else:
+            return f"postgresql://{self.pg_user}:{urllib.parse.quote(self.pg_passwd)}@{self.pg_host}:{self.pg_port}/{self.pg_dbname}" # type: ignore
+    
+    def log_config(self) -> None:
+        """Log database configuration (excluding password)"""
+        logging.info("===Database Config===")
+        logging.info(f"user : {self.pg_user}")
+        logging.info("Passwd : ********")
+        logging.info(f"dbname : {self.pg_dbname}")
+        logging.info(f"host : {self.pg_host}")
+        logging.info(f"port : {self.pg_port}")
+        logging.info(f"use_sqlite_db : {self.use_sqlite_db}")

contentgrid_assistant_api/db/repositories/thread_repository.py

@@ -0,0 +1,78 @@
+
+from typing import List, Optional
+import uuid
+from pydantic import HttpUrl
+from sqlmodel import Session, select
+from fastapi import HTTPException
+from contentgrid_extension_helpers.dependencies.sqlalch.repositories import BaseRepository
+from contentgrid_assistant_api.db.types.thread import Thread, ThreadCreate, ThreadUpdate
+from contentgrid_extension_helpers.dependencies.authentication.user import ContentGridUser
+
+
+class ThreadRepository(BaseRepository[Thread, ThreadCreate, ThreadUpdate]):
+    """Repository for Thread operations"""
+    
+    def __init__(self, session: Session):
+        super().__init__(session, Thread)
+    
+    def create(self, user: ContentGridUser, origin : Optional[HttpUrl], component : str, thread_id : uuid.UUID | None = None) -> Thread:
+        """Create a new thread, associating it with the user"""
+        thread_params = {
+            "name" : "New Thread",
+            "origin" : origin.encoded_string() if origin else None,
+            "component" : component,
+            "user_sub" : user.sub
+        }
+        
+        if thread_id:
+            thread_params["id"] = thread_id
+            
+        new_thread = Thread(
+            **thread_params
+        )
+        self.session.add(new_thread)
+        self.session.commit()
+        self.session.refresh(new_thread)
+        return new_thread
+    
+    def get_all_for_user(self, user: ContentGridUser, offset: int = 0, limit: int = 100) -> List[Thread]:
+        """Get all threads for a specific user with pagination"""
+        return self.session.exec(
+            select(Thread).where(Thread.user_sub == user.sub).offset(offset).limit(limit)
+        ).all()
+        
+    def get_all_for_user_and_origin(self, user: ContentGridUser, origin: HttpUrl, offset: int = 0, limit: int = 100) -> List[Thread]:
+        """Get all threads for a specific user and origin"""
+        return self.session.exec(
+            select(Thread).where(Thread.user_sub == user.sub, Thread.origin == origin.encoded_string()).offset(offset).limit(limit)
+        ).all()
+    
+    def get_by_id_for_user(self, thread_id: uuid.UUID, user: ContentGridUser) -> Thread:
+        """Get thread by ID, ensuring it belongs to the user"""
+        dataset = self.session.exec(
+            select(Thread).where(Thread.id == thread_id, Thread.user_sub == user.sub)
+        ).first()
+        if not dataset:
+            raise HTTPException(status_code=404, detail="Thread not found or access denied")
+        return dataset
+    
+    def update_for_user(self, thread_id: uuid.UUID, update_model: ThreadUpdate, user: ContentGridUser) -> Thread:
+        """Update thread, ensuring it belongs to the user"""
+        thread = self.get_by_id_for_user(thread_id, user)
+        
+        # Apply updates
+        update_data = update_model.model_dump(exclude_unset=True)
+        for field, value in update_data.items():
+            setattr(thread, field, value)
+        
+        self.session.add(thread)
+        self.session.commit()
+        self.session.refresh(thread)
+        return thread
+    
+    def delete_for_user(self, thread_id: uuid.UUID, user: ContentGridUser) -> Thread:
+        """Delete thread, ensuring it belongs to the user"""
+        thread = self.get_by_id_for_user(thread_id, user)
+        self.session.delete(thread)
+        self.session.commit()
+        return thread

contentgrid_assistant_api/db/types/message.py

@@ -0,0 +1,25 @@
+from langchain_core.messages import HumanMessage, SystemMessage, AIMessage, ToolMessage, UsageMetadata
+from contentgrid_extension_helpers.responses.hal import FastAPIHALResponse
+from pydantic import Field
+
+
+class BaseHALMessage(FastAPIHALResponse):
+    hidden : bool = False
+    additional_kwargs: dict = Field(exclude=True) # exclude removes the output from the serialization
+    response_metadata: dict = Field(exclude=True)
+
+    def get(self, key, default=None):
+        """Add get method for compatibility with LangChain validation"""
+        return getattr(self, key, default)
+    
+class HALHumanMessage(BaseHALMessage, HumanMessage):
+    pass
+        
+class HALAIMessage(BaseHALMessage, AIMessage):
+    usage_metadata: UsageMetadata | None = Field(exclude=True)
+        
+class HALSystemMessage(BaseHALMessage, SystemMessage):
+    hidden : bool = True
+
+class HALToolMessage(BaseHALMessage, ToolMessage):
+    pass

contentgrid_assistant_api/db/types/thread.py

@@ -0,0 +1,46 @@
+from enum import Enum
+from typing import Optional, List
+import uuid
+from pydantic import BaseModel
+from datetime import datetime
+from sqlmodel import Field, SQLModel
+from contentgrid_extension_helpers.responses.hal import FastAPIHALResponse, HALLinkFor, HALTemplateFor, HALLink
+
+class ThreadBase(SQLModel):
+    # Base model for Thread
+    # Not used on its own, but as a base for Thread, ThreadCreate.
+    # ThreadUpdate inherits from Basemodel. Meaning only the fields there can be patched.
+    # All fields set here will be inherited so are therefore publicly accessible
+    # For private fields that should not be publicly accessible, use the main Thread class
+    id : uuid.UUID = Field(primary_key=True, default_factory=uuid.uuid4)
+    name: str = Field(description="Name of the Thread")
+    origin : Optional[str] = Field(index=True)
+    component: str = Field(index=True, default="Undefined")
+    created_at : datetime = Field(default_factory=datetime.now, description="Creation timestamp")
+    
+class Thread(ThreadBase, table=True):
+    # Main Thread model, this is the model where you will code your business logic with
+    user_sub : str = Field(index=True, description="User subject (sub) who owns the Thread")
+
+class ThreadRead(ThreadBase, FastAPIHALResponse):
+    # A read-only version of the Thread model that can be used for public API responses
+    # Note that this model inherits from ThreadBase, so it has the same fields
+
+    def __init__(self, tags: Optional[List[str | Enum]]=None, **kwargs):
+        super().__init__(**kwargs)
+        self.links = {
+            "self": HALLinkFor(endpoint_function_name="read_thread", tags=tags, templated=False, path_params=lambda instance: {"thread_id": instance.id}),
+            "messages": HALLinkFor(endpoint_function_name="read_messages", tags=tags, templated=False, path_params=lambda instance: {"thread_id": instance.id}),
+            "tools": HALLinkFor(endpoint_function_name="get_thread_tools", tags=tags, templated=False, path_params=lambda instance: {"thread_id": instance.id}),
+        }
+        self.templates = {
+            "update": HALTemplateFor(endpoint_function_name="update_thread", tags=tags, templated=False, path_params=lambda instance: {"thread_id": instance.id}),
+            "delete": HALTemplateFor(endpoint_function_name="delete_thread", tags=tags, templated=False, path_params=lambda instance: {"thread_id": instance.id})
+        }
+
+class ThreadCreate(ThreadBase):
+    # Creating a thread will be done by injecting the user_sub and origin from the dependencies.
+    pass
+
+class ThreadUpdate(BaseModel):
+    name : str = Field(None, description="New name of the Thread") # type: ignore

contentgrid_assistant_api/dependencies.py

@@ -0,0 +1,79 @@
+from typing import Generator
+import uuid
+from fastapi import Depends
+from fastapi.security import OAuth2PasswordBearer
+from sqlmodel import Session
+from contentgrid_assistant_api.db.repositories.thread_repository import ThreadRepository
+from contentgrid_extension_helpers.dependencies.sqlalch.db import SQLiteSessionFactory, PostgresSessionFactory
+from contentgrid_extension_helpers.dependencies.authentication.user import ContentGridUser
+from langgraph.checkpoint.postgres import PostgresSaver
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.checkpoint.base import BaseCheckpointSaver
+from langgraph.graph.state import CompiledStateGraph
+from contentgrid_assistant_api.types.context import DefaultThreadContext
+from contentgrid_assistant_api.config import DatabaseConfig
+from contentgrid_assistant_api.types.agents import Agent
+
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+
+class DependencyResolver():
+    def __init__(self, agent : Agent, db_config : DatabaseConfig) -> None:
+        db_config.pg_dbname = agent.name
+        self.agent = agent
+        self.db_config = db_config
+        if db_config.use_sqlite_db:
+            self.db_conn_factory = SQLiteSessionFactory(sqlite_file_name=f"{agent.name}.db")
+            self.in_mem_store = MemorySaver()
+        else:
+            self.db_conn_factory = PostgresSessionFactory(
+                pg_host=db_config.pg_host,
+                pg_dbname=db_config.pg_dbname,
+                pg_user=db_config.pg_user,
+                pg_passwd=db_config.pg_passwd,
+                pg_port=db_config.pg_port
+            )
+            # Only setup PostgreSQL checkpointer if not using SQLite
+            with PostgresSaver.from_conn_string(db_config.database_url) as store:
+                store.setup()
+        
+    def get_langgraph_checkpointer_dependency(self):
+        def get_langgraph_checkpointer() -> Generator[BaseCheckpointSaver, None, None]:
+            if self.db_config.use_sqlite_db:
+                yield self.in_mem_store
+            elif "postgresql" in self.db_config.database_url:
+                with PostgresSaver.from_conn_string(self.db_config.database_url) as store:
+                    yield store
+        return get_langgraph_checkpointer
+    
+    
+    def get_thread_repository_dependency(self):
+        def get_thread_repository(session: Session = Depends(self.db_conn_factory)) -> ThreadRepository:
+            """Get a dataset repository instance"""
+            return ThreadRepository(session)
+        return get_thread_repository
+    
+    def get_thread_context_dependency(self):
+        def get_thread_context(thread_id: uuid.UUID, thread_repository: ThreadRepository = Depends(self.get_thread_repository_dependency()), user: ContentGridUser = Depends(self.get_current_user_dependency())) -> DefaultThreadContext:
+            # Getting the Conversation context from the incoming request.
+            # This dependency can only be used on /{thread_id}/... endpoints
+            # Each thread is related to a possible origin, using the thread_id we fetch that origin using the thread_repository.
+            # If the user is not allowed to read the thread, the database won't return the thread and the request is terminated with 404 early.
+            # If the user is allowed to read, the origin from the database is injected in the conversation context which tools can access.
+            # ThreadContext shows all fields in the thread's context of the user.
+            thread = thread_repository.get_by_id_for_user(thread_id=thread_id, user=user)
+            # Here we could check if the user is still allowed to reach the origin. 
+            # > This should be done in the agent graphs. Or you can let the tools fail or add a graph that fetches the origin (like fetch datamodel in the console assistant or fetch profile in the navigator assistant)
+            # btw mypy complains about messages not being passed but that is not good because then the conversation is empty. so do not pass messages here. it should come from the postgres persistance.
+            return self.agent.thread_context(user=user, origin=thread.origin, thread_id=str(thread_id)) # type: ignore
+        return get_thread_context
+    
+    def get_agent_dependency(self):
+        def get_agent(checkpointer: BaseCheckpointSaver = Depends(self.get_langgraph_checkpointer_dependency())) -> CompiledStateGraph:
+            return self.agent.get_agent_override(checkpointer=checkpointer)
+        return get_agent
+    
+    def get_current_user_dependency(self):
+        if self.agent.get_current_user_override:
+            return self.agent.get_current_user_override
+        raise Exception("Get current user dependency not set...")

contentgrid_assistant_api/routers/agent_home.py

@@ -0,0 +1,41 @@
+from fastapi import APIRouter, FastAPI
+import os
+from fastapi.concurrency import asynccontextmanager
+from contentgrid_assistant_api.config import DatabaseConfig, AssistantExtensionConfig
+from contentgrid_assistant_api.dependencies import DependencyResolver
+from contentgrid_assistant_api.routers.thread_router import generate_agent_thread_router
+from contentgrid_assistant_api.types.agents import Agent, AgentHomeResponse
+
+def exit_uvicorn():
+    import signal
+    # Send interrupt signal (Ctrl+C equivalent) to uvicorn (parent process)
+    # This is a bit of a janky way to "gracefully crash" the process, but it should suffice for now.
+    os.kill(os.getppid(), signal.SIGINT)
+
+
+def generate_agent_home_router(agent : Agent, extension_config: AssistantExtensionConfig, database_config: DatabaseConfig) -> APIRouter:
+    if database_config.pg_dbname == database_config.__class__.model_fields["pg_dbname"].default:
+        # Check if the pg_dbname is still the default, if yes use the agent name
+        database_config.pg_dbname = agent.name
+        
+    dep_resolver = DependencyResolver(agent=agent, db_config=database_config)
+    
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        if database_config.pg_reinitialize:
+            # Clean up the threads and wipe the database
+            dep_resolver.db_conn_factory.wipe_database()
+        # Lifespan of the fast API router. Code before the yield is executed when the application starts
+        # and code after the yield is executed when the application stops.
+        dep_resolver.db_conn_factory.create_db_and_tables()
+        yield
+        
+        
+    router = APIRouter(lifespan=lifespan, tags=[agent.name])
+    router.include_router(generate_agent_thread_router(dep_resolver, extension_config, tags=[agent.name]))
+    
+    @router.get("/", response_model=AgentHomeResponse, response_model_exclude_unset=True)
+    def get_agent_home():
+        return AgentHomeResponse(**agent.model_dump(), tags=[agent.name])
+
+    return router