contentgrid-assistant-api 0.0.2__tar.gz → 0.0.4__tar.gz

{contentgrid_assistant_api-0.0.2/src/contentgrid_assistant_api.egg-info → contentgrid_assistant_api-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contentgrid-assistant-api
-Version: 0.0.2
+Version: 0.0.4
 Summary: FastAPI wrapper for contentgrid assistants
 Author-email: Ranec Belpaire <ranec.belpaire@xenit.eu>
 License: Copyright 2024 Xenit Solutions
@@ -30,6 +30,7 @@ Requires-Dist: langchain>=1.2.3
 Requires-Dist: langchain_openai>=1.1.7
 Requires-Dist: langgraph>=1.0.5
 Requires-Dist: langgraph-checkpoint-postgres>=3.0.2
+Requires-Dist: langfuse>=3.0.0
 Requires-Dist: python-dotenv>=1.1.1
 Requires-Dist: requests<3,>=2.32.5
 Requires-Dist: types-requests>=2.32.4

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4}/pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "langchain_openai >= 1.1.7",
     "langgraph >= 1.0.5",
     "langgraph-checkpoint-postgres >= 3.0.2",
+    "langfuse >= 3.0.0",
     "python-dotenv >= 1.1.1",
     "requests >= 2.32.5, < 3",
     "types-requests >= 2.32.4",

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4}/src/contentgrid_assistant_api/app.py

@@ -1,5 +1,6 @@
 import logging
-from typing import List
+from contextlib import asynccontextmanager
+from typing import List, Optional
 from fastapi import Depends, FastAPI, status, Request
 from fastapi.middleware.cors import CORSMiddleware
 from openai import APIError
@@ -9,8 +10,10 @@ 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.config import AssistantExtensionConfig, DatabaseConfig, LangfuseConfig
 from contentgrid_assistant_api.types.agents import Agent, AgentHomeResponse
+from contentgrid_assistant_api.tracing import setup_langfuse, shutdown_langfuse
+from pydantic import HttpUrl
 
 
 class ContentGridAssistantAPI(FastAPI):
@@ -18,14 +21,16 @@ class ContentGridAssistantAPI(FastAPI):
     
     def __init__(self, 
                  extension_config: AssistantExtensionConfig | None = None, 
-                 database_config: DatabaseConfig | None = None, 
+                 database_config: DatabaseConfig | None = None,
+                 langfuse_config: LangfuseConfig | 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.langfuse_config = langfuse_config or LangfuseConfig()
         
         self._setup_logging()
+        super().__init__(*args, lifespan=self._lifespan, **kwargs)
         if not self.extension_config.production:
             self._setup_cors()
         self._setup_hal_response()
@@ -54,6 +59,13 @@ class ContentGridAssistantAPI(FastAPI):
         if self.extension_config.production:
             setup_json_logging()
     
+    @asynccontextmanager
+    async def _lifespan(self, app: "ContentGridAssistantAPI"):
+        """Manage application lifespan: initialize and shut down Langfuse."""
+        setup_langfuse(self.langfuse_config)
+        yield
+        shutdown_langfuse(self.langfuse_config)
+    
     def _setup_cors(self):
         """Configure CORS middleware"""
         self.add_middleware(
@@ -89,11 +101,11 @@ class ContentGridAssistantAPI(FastAPI):
             return "ok"
         
         @self.get(f"{self._server_prefix}/", response_model=FastAPIHALCollection, response_model_exclude_unset=True)
-        def get_server_resources():
+        def get_server_resources(origin: Optional[HttpUrl] = None):
             return FastAPIHALCollection(
                 _embedded={
                     "agents" : [
-                        AgentHomeResponse(**agent.model_dump(), tags=[agent.name]) for agent in agents
+                        AgentHomeResponse(**agent.model_dump(), origin=origin, tags=[agent.name]) for agent in agents
                     ] 
                 },
                 _links={

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4}/src/contentgrid_assistant_api/config.py

@@ -1,9 +1,32 @@
 from pydantic_settings import BaseSettings
 from pydantic import Field, ConfigDict
 from pydantic import computed_field
+from typing import Optional
 import logging
 import urllib
 
+class LangfuseConfig(BaseSettings):
+    """Configuration for Langfuse observability.
+    
+    Set these environment variables to enable tracing:
+    - LANGFUSE_SECRET_KEY: Your Langfuse secret key (sk-lf-...)
+    - LANGFUSE_PUBLIC_KEY: Your Langfuse public key (pk-lf-...)
+    - LANGFUSE_BASE_URL: Langfuse server URL (default: https://cloud.langfuse.com)
+    """
+    model_config = ConfigDict(extra="allow", env_file=[".env", ".env.secret"], env_file_encoding="utf-8")
+    
+    langfuse_secret_key: Optional[str] = Field(default=None)
+    langfuse_public_key: Optional[str] = Field(default=None)
+    langfuse_base_url: str = Field(default="https://cloud.langfuse.com")
+    langfuse_enabled: bool = Field(default=True, description="Enable/disable Langfuse tracing")
+    
+    @computed_field
+    @property
+    def is_configured(self) -> bool:
+        """Check if Langfuse credentials are configured"""
+        return bool(self.langfuse_secret_key and self.langfuse_public_key and self.langfuse_enabled)
+
+
 class AssistantExtensionConfig(BaseSettings):
     model_config = ConfigDict(extra="allow", env_file=[".env", ".env.secret"], env_file_encoding="utf-8")
     

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4}/src/contentgrid_assistant_api/routers/agent_home.py

@@ -1,10 +1,13 @@
+from typing import Optional
+
 from fastapi import APIRouter, FastAPI
 import os
 from fastapi.concurrency import asynccontextmanager
-from contentgrid_assistant_api.config import DatabaseConfig, AssistantExtensionConfig
+from contentgrid_assistant_api.config import DatabaseConfig, AssistantExtensionConfig, LangfuseConfig
 from contentgrid_assistant_api.dependencies import DependencyResolver
-from contentgrid_assistant_api.routers.thread_router import generate_agent_thread_router
+from contentgrid_assistant_api.routers.thread_router import HALLinkFor, generate_agent_thread_router
 from contentgrid_assistant_api.types.agents import Agent, AgentHomeResponse
+from pydantic import HttpUrl
 
 def exit_uvicorn():
     import signal
@@ -13,10 +16,18 @@ def exit_uvicorn():
     os.kill(os.getppid(), signal.SIGINT)
 
 
-def generate_agent_home_router(agent : Agent, extension_config: AssistantExtensionConfig, database_config: DatabaseConfig) -> APIRouter:
+def generate_agent_home_router(
+    agent: Agent,
+    extension_config: AssistantExtensionConfig,
+    database_config: DatabaseConfig,
+    langfuse_config: LangfuseConfig | None = None
+) -> 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
+    
+    # Use provided langfuse_config or create default
+    langfuse_cfg = langfuse_config or LangfuseConfig()
         
     dep_resolver = DependencyResolver(agent=agent, db_config=database_config)
     
@@ -32,10 +43,15 @@ def generate_agent_home_router(agent : Agent, extension_config: AssistantExtensi
         
         
     router = APIRouter(lifespan=lifespan, tags=[agent.name])
-    router.include_router(generate_agent_thread_router(dep_resolver, extension_config, tags=[agent.name]))
+    router.include_router(generate_agent_thread_router(
+        dep_resolver,
+        extension_config,
+        langfuse_config=langfuse_cfg,
+        agent_name=agent.name,
+        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])
-
+    def get_agent_home(origin: Optional[HttpUrl] = None):
+        return AgentHomeResponse(**agent.model_dump(), origin=origin, tags=[agent.name])
     return router

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4}/src/contentgrid_assistant_api/routers/message_router.py

@@ -6,10 +6,11 @@ from typing import Annotated, AsyncGenerator, List, Union, Optional
 import typing
 import uuid
 from enum import Enum
+from contentgrid_assistant_api.tracing import _create_langfuse_config
 from langgraph.graph.state import CompiledStateGraph
 from fastapi import APIRouter, BackgroundTasks, File, Form, Request, UploadFile, status
 from fastapi.params import Depends
-from contentgrid_assistant_api.config import AssistantExtensionConfig
+from contentgrid_assistant_api.config import AssistantExtensionConfig, LangfuseConfig
 from fastapi.responses import StreamingResponse
 from contentgrid_assistant_api.db.repositories.thread_repository import ThreadRepository
 from contentgrid_assistant_api.db.types.message import HALHumanMessage, HALAIMessage, HALSystemMessage, HALToolMessage
@@ -20,14 +21,20 @@ from contentgrid_extension_helpers.responses.hal import FastAPIHALCollection, HA
 from langchain_core.messages import HumanMessage, SystemMessage, AIMessage, BaseMessage, ToolMessage
 from fastapi import HTTPException
 
-
 # ContentBlocks
 from langchain_core.messages.content import create_image_block, create_file_block, create_audio_block, create_text_block, ImageContentBlock, AudioContentBlock, FileContentBlock, TextContentBlock
 import logging
 
 from contentgrid_assistant_api.types.context import DefaultThreadContext
 
-def generate_agent_message_router(dep_resolver: DependencyResolver, extension_config: AssistantExtensionConfig, tags: Optional[List[str | Enum]]=None) -> APIRouter:
+
+def generate_agent_message_router(
+    dep_resolver: DependencyResolver,
+    extension_config: AssistantExtensionConfig,
+    langfuse_config: LangfuseConfig,
+    agent_name: str,
+    tags: Optional[List[str | Enum]] = None
+) -> APIRouter:
     messagesrouter = APIRouter(prefix="/{thread_id}" + extension_config.routes_message_prefix, tags=tags or ["messages"])
 
     def convert_to_hal_message(message: BaseMessage, thread_id: uuid.UUID) -> Union[HALHumanMessage, HALAIMessage, HALSystemMessage, HALToolMessage]:
@@ -160,6 +167,9 @@ def generate_agent_message_router(dep_resolver: DependencyResolver, extension_co
         new_message = HumanMessage(content=content_blocks) # type: ignore
         messages = [new_message]
         
+        # Create Langfuse config with session_id, user_id, and tags for observability
+        lf_config = _create_langfuse_config(thread_context, user, agent_name, langfuse_config)
+        
         if streaming:
             state = agent.get_state(config={"configurable" : thread_context}) #type: ignore
             nb_current_messages = 0
@@ -168,9 +178,15 @@ def generate_agent_message_router(dep_resolver: DependencyResolver, extension_co
 
             @typing.no_type_check
             async def generate_stream(current_message_index) -> AsyncGenerator[str, None]:
+                # Merge Langfuse config with LangGraph config
+                stream_config = {
+                    "configurable": thread_context,
+                    "recursion_limit": extension_config.graph_recursion_limit,
+                    **lf_config
+                }
                 for mode, chunk in agent.stream(
                     {"messages": messages},
-                    {"configurable": thread_context, "recursion_limit": extension_config.graph_recursion_limit},
+                    stream_config,
                     context=thread_context,
                     stream_mode=["values", "messages"]
                 ):
@@ -214,11 +230,18 @@ def generate_agent_message_router(dep_resolver: DependencyResolver, extension_co
                 }
             )
         else:
+            # Capture lf_config for closure
+            invoke_config = {
+                "configurable": thread_context,
+                "recursion_limit": extension_config.graph_recursion_limit,
+                **lf_config
+            }
+            
             def process_agent_response():
                 try:
                     agent.invoke(
                         {"messages": messages},
-                        {"configurable": thread_context, "recursion_limit": extension_config.graph_recursion_limit},
+                        invoke_config,
                         context=thread_context,
                     )
                 except Exception as e:

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4}/src/contentgrid_assistant_api/routers/thread_router.py

@@ -2,6 +2,7 @@
 from enum import Enum
 from typing import Annotated, List, Optional
 import uuid
+from contentgrid_assistant_api.tracing import _create_langfuse_config_for_thread
 from fastapi import APIRouter, Depends, Query, status
 from pydantic import HttpUrl
 
@@ -15,13 +16,29 @@ from contentgrid_assistant_api.types.agents import AgentToolCollectionResponse,
 from contentgrid_assistant_api.types.context import DefaultThreadContext
 from langchain.messages import HumanMessage
 from langgraph.graph.state import CompiledStateGraph
-from contentgrid_assistant_api.config import AssistantExtensionConfig
+from contentgrid_assistant_api.config import AssistantExtensionConfig, LangfuseConfig
+
+
+def generate_agent_thread_router(
+    dep_resolver: DependencyResolver,
+    extension_config: AssistantExtensionConfig,
+    langfuse_config: LangfuseConfig | None = None,
+    agent_name: str = "agent",
+    tags: Optional[List[str | Enum]] = None
+):
+    # Use provided langfuse_config or create default
+    langfuse_cfg = langfuse_config or LangfuseConfig()
     
-def generate_agent_thread_router(dep_resolver: DependencyResolver, extension_config: AssistantExtensionConfig, tags: Optional[List[str | Enum]]=None):
     threadrouter = APIRouter(prefix=extension_config.routes_thread_prefix, tags=tags or ["threads"])
 
     threadrouter.include_router(
-        generate_agent_message_router(dep_resolver, extension_config, tags=tags)
+        generate_agent_message_router(
+            dep_resolver,
+            extension_config,
+            langfuse_config=langfuse_cfg,
+            agent_name=agent_name,
+            tags=tags
+        )
     )
 
     @threadrouter.post("/", response_model=ThreadRead, status_code=status.HTTP_201_CREATED, response_model_exclude_none=True)
@@ -36,9 +53,17 @@ def generate_agent_thread_router(dep_resolver: DependencyResolver, extension_con
         thread_id = uuid.uuid4()
         messages = [HumanMessage(content=extension_config.opening_message)]
         context = dep_resolver.agent.thread_context(thread_id=str(thread_id), user=user, origin=origin)
+        
+        # Create Langfuse config for thread creation tracing
+        lf_config = _create_langfuse_config_for_thread(str(thread_id), user, agent_name, langfuse_cfg, extra_tags=["create-thread"])
+        invoke_config = {
+            "configurable": context,
+            **lf_config
+        }
+        
         agent.invoke(
             {"messages": messages},
-            {"configurable": context}, #type: ignore
+            invoke_config, #type: ignore
             context=context, #type: ignore
         )
         

contentgrid_assistant_api-0.0.4/src/contentgrid_assistant_api/tracing.py

@@ -0,0 +1,67 @@
+
+import logging
+from contentgrid_assistant_api.config import LangfuseConfig
+from contentgrid_assistant_api.types.context import ContentGridUser, DefaultThreadContext
+
+
+def setup_langfuse(langfuse_config: LangfuseConfig) -> None:
+    """Initialize the Langfuse observability client."""
+    if langfuse_config.is_configured:
+        from langfuse import Langfuse
+        Langfuse(
+            public_key=langfuse_config.langfuse_public_key,
+            secret_key=langfuse_config.langfuse_secret_key,
+            base_url=langfuse_config.langfuse_base_url,
+        )
+        logging.info("Langfuse observability initialized successfully")
+    else:
+        logging.info("Langfuse not configured - tracing disabled. Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY to enable.")
+
+
+def shutdown_langfuse(langfuse_config: LangfuseConfig) -> None:
+    """Flush and shut down the Langfuse client."""
+    if langfuse_config.is_configured:
+        from langfuse import get_client
+        get_client().shutdown()
+        logging.info("Langfuse client shutdown complete")
+
+
+def _create_langfuse_config_for_thread(
+    thread_id: str,
+    user: ContentGridUser,
+    agent_name: str,
+    langfuse_config: LangfuseConfig,
+    extra_tags: list[str] | None = None
+) -> dict:
+    """Create LangChain config with Langfuse callback handler and metadata.
+    
+    Per Langfuse best practices:
+    - session_id: Groups conversation messages together (using thread_id)
+    - user_id: Enables user filtering and cost attribution
+    - tags: Per-feature analytics (using agent name)
+    """
+    config: dict = {}
+    
+    if langfuse_config.is_configured:
+        try:
+            from langfuse.langchain import CallbackHandler
+            langfuse_handler = CallbackHandler()
+            config["callbacks"] = [langfuse_handler]
+            config["metadata"] = {
+                "langfuse_session_id": thread_id,
+                "langfuse_user_id": user.sub,
+                "langfuse_tags": [agent_name] + (extra_tags or [])
+            }
+        except ImportError:
+            logging.warning("Langfuse not installed, tracing disabled")
+    
+    return config
+
+def _create_langfuse_config(
+    thread_context: DefaultThreadContext,
+    user: ContentGridUser,
+    agent_name: str,
+    langfuse_config: LangfuseConfig
+) -> dict:
+    """Create LangChain config with Langfuse callback handler for an existing thread."""
+    return _create_langfuse_config_for_thread(thread_context.thread_id, user, agent_name, langfuse_config)

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4}/src/contentgrid_assistant_api/types/agents.py

@@ -2,7 +2,7 @@
 from typing import Any, Callable, List, Optional
 from enum import Enum
 import uuid
-from pydantic import BaseModel, Field, ConfigDict
+from pydantic import BaseModel, Field, ConfigDict, HttpUrl
 from langchain.tools import BaseTool
 from contentgrid_extension_helpers.responses.hal import FastAPIHALResponse, FastAPIHALCollection, HALLinkFor
 from contentgrid_assistant_api.types.context import DefaultThreadContext
@@ -25,11 +25,12 @@ class AgentHomeResponse(FastAPIHALResponse):
     name : str
     version : str
     
-    def __init__(self, tags: Optional[List[str | Enum]]=None, **kwargs):
+    def __init__(self, origin: Optional[HttpUrl] = None, tags: Optional[List[str | Enum]] = None, **kwargs):
         super().__init__(**kwargs)
+        params = {"origin": str(origin)} if origin else {}
         self.links = {
-            "self" : HALLinkFor(endpoint_function_name="get_agent_home", tags=tags),
-            "threads" : HALLinkFor(endpoint_function_name="read_threads", tags=tags),
+            "self": HALLinkFor(endpoint_function_name="get_agent_home", params=params, tags=tags),
+            "threads": HALLinkFor(endpoint_function_name="read_threads",   params=params, tags=tags),
         }
     
 class AgentToolResponse(FastAPIHALResponse):

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4/src/contentgrid_assistant_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contentgrid-assistant-api
-Version: 0.0.2
+Version: 0.0.4
 Summary: FastAPI wrapper for contentgrid assistants
 Author-email: Ranec Belpaire <ranec.belpaire@xenit.eu>
 License: Copyright 2024 Xenit Solutions
@@ -30,6 +30,7 @@ Requires-Dist: langchain>=1.2.3
 Requires-Dist: langchain_openai>=1.1.7
 Requires-Dist: langgraph>=1.0.5
 Requires-Dist: langgraph-checkpoint-postgres>=3.0.2
+Requires-Dist: langfuse>=3.0.0
 Requires-Dist: python-dotenv>=1.1.1
 Requires-Dist: requests<3,>=2.32.5
 Requires-Dist: types-requests>=2.32.4

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4}/src/contentgrid_assistant_api.egg-info/SOURCES.txt

@@ -6,10 +6,13 @@ setup.py
 src/contentgrid_assistant_api/app.py
 src/contentgrid_assistant_api/config.py
 src/contentgrid_assistant_api/dependencies.py
+src/contentgrid_assistant_api/tracing.py
 src/contentgrid_assistant_api.egg-info/PKG-INFO
 src/contentgrid_assistant_api.egg-info/SOURCES.txt
 src/contentgrid_assistant_api.egg-info/dependency_links.txt
 src/contentgrid_assistant_api.egg-info/requires.txt
+src/contentgrid_assistant_api.egg-info/scm_file_list.json
+src/contentgrid_assistant_api.egg-info/scm_version.json
 src/contentgrid_assistant_api.egg-info/top_level.txt
 src/contentgrid_assistant_api/db/repositories/thread_repository.py
 src/contentgrid_assistant_api/db/types/message.py

{contentgrid_assistant_api-0.0.2 → contentgrid_assistant_api-0.0.4}/src/contentgrid_assistant_api.egg-info/requires.txt

@@ -6,6 +6,7 @@ langchain>=1.2.3
 langchain_openai>=1.1.7
 langgraph>=1.0.5
 langgraph-checkpoint-postgres>=3.0.2
+langfuse>=3.0.0
 python-dotenv>=1.1.1
 requests<3,>=2.32.5
 types-requests>=2.32.4

contentgrid_assistant_api-0.0.4/src/contentgrid_assistant_api.egg-info/scm_file_list.json

@@ -0,0 +1,24 @@
+{
+  "files": [
+    "README.md",
+    "LICENSE",
+    "setup.py",
+    "pyproject.toml",
+    "pytest.ini",
+    "src/contentgrid_assistant_api/dependencies.py",
+    "src/contentgrid_assistant_api/config.py",
+    "src/contentgrid_assistant_api/app.py",
+    "src/contentgrid_assistant_api/tracing.py",
+    "src/contentgrid_assistant_api/db/repositories/thread_repository.py",
+    "src/contentgrid_assistant_api/db/types/message.py",
+    "src/contentgrid_assistant_api/db/types/thread.py",
+    "src/contentgrid_assistant_api/types/context.py",
+    "src/contentgrid_assistant_api/types/agents.py",
+    "src/contentgrid_assistant_api/routers/agent_home.py",
+    "src/contentgrid_assistant_api/routers/message_router.py",
+    "src/contentgrid_assistant_api/routers/thread_router.py",
+    "tests/test_tools_endpoint.py",
+    "tests/test_thread_access_control.py",
+    "tests/mock_agent.py"
+  ]
+}

contentgrid_assistant_api-0.0.4/src/contentgrid_assistant_api.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.0.4",
+  "distance": 0,
+  "node": "ga52e3de53c38aa2efe3e7fd89c795fc33c7ac189",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-04-22"
+}