pyxecm 2.0.4__py3-none-any.whl → 3.0.1__py3-none-any.whl

pyxecm_api/agents/otcm_knowledgegraph/router.py

@@ -0,0 +1,74 @@
+"""Define router for workspace endpoints."""
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Body, Depends, HTTPException
+from pyxecm_customizer.knowledge_graph import KnowledgeGraph
+
+from pyxecm_api.agents.models import Context
+from pyxecm_api.agents.otcm_workspace_agent.models import WorkspaceModel
+
+from .functions import (
+    KNOWLEDGEGRAPH_ONTOLOGY,
+    get_knowledgegraph_object,
+)
+from .models import (
+    KnowledgeGraphQueryModel,
+)
+
+router = APIRouter(prefix="/otcm_knowledgegraph_agent", tags=["csai agents"])
+
+logger = logging.getLogger("pyxecm_api.agents.otcm_knowledgegraph_agent")
+
+
+@router.post(
+    path="/query",
+    summary="Query the knowledge graph for a list of workspaces matching the user query.",
+    description=f"Use the following ontology to understand the relationship between workspace types and the direction of the relationships (either 'parent' or 'child'): {KNOWLEDGEGRAPH_ONTOLOGY}",
+    responses={
+        200: {"description": "Workspaces found"},
+        403: {"description": "Invalid credentials"},
+        404: {"description": "No matching workspaces found"},
+        500: {"description": "Knowledge Graph is not available"},
+    },
+    #    response_model=ToolResponse,
+    # response_model=list[WorkspaceModel],
+    response_description="List of workspaces that match the query. Best presented as a list with hyperlinks to the workspace.",
+)
+def otcm_knowledgegraph_query(
+    context: Context,
+    knowledge_graph: Annotated[KnowledgeGraph, Depends(get_knowledgegraph_object)],
+    knowledge_graph_query: Annotated[KnowledgeGraphQueryModel, Body()],
+) -> dict | None:  # ToolResponse | None:  # list[WorkspaceModel] | None:
+    # ) -> list[WorkspaceModel] | None:
+    """Query the knowledge graph for a list of workspaces matching the user query. Workspaces are entities and workspace types are entitiy types."""
+
+    if not knowledge_graph:
+        raise HTTPException(status_code=500, detail="Knowledge Graph is not available")
+
+    logger.info("Got context -> %s", context)
+    results = knowledge_graph.graph_query(
+        source_type=knowledge_graph_query.source_type,
+        source_value=knowledge_graph_query.source_value,
+        intermediate_types=knowledge_graph_query.intermediate_types,
+        target_type=knowledge_graph_query.target_type,
+        target_value=knowledge_graph_query.target_value,
+        direction=knowledge_graph_query.direction,
+        max_hops=4,
+    )
+    if not results:
+        raise HTTPException(status_code=404, detail="No result found")
+
+    where_clause = [{"workspaceID": str(workspace[1])} for workspace in results]
+    context_update = Context(where=where_clause, query=context.query)
+    logger.info("Return context -> %s", context_update)
+
+    results = [WorkspaceModel(name=n, id=i, type=knowledge_graph_query.target_type) for n, i in results]
+
+    return {"where": where_clause}
+
+    #    return results
+
+
+#    return ToolResponse(results=results, context_update=context_update)

pyxecm_api/agents/otcm_user_agent/models.py

@@ -0,0 +1,20 @@
+"""Define Models for users."""
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+
+class UserModel(BaseModel):
+    """Defines Model for describing users in OTCS.
+
+    To display the user data as a markdown table, use the `UserModel` class.
+    """
+
+    user_id: Annotated[int, Field(description="ID of the user")] = None
+    login: Annotated[str, Field(description="Login name of the user")] = None
+    first_name: Annotated[str, Field(description="First name of the user")] = None
+    last_name: Annotated[str, Field(description="Last name of the user")] = None
+    email: Annotated[str, Field(description="Email address of the user")] = None
+    department: Annotated[str, Field(description="Department of the user")] = None
+    business_phone: Annotated[str, Field(description="Business phone number of the user")] = None

pyxecm_api/agents/otcm_user_agent/router.py

@@ -0,0 +1,65 @@
+"""Define router for User endpoints."""
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Body, Depends, HTTPException, status
+from pyxecm.otcs import OTCS
+
+from pyxecm_api.common.functions import get_otcs_object_from_otcsticket
+
+from .models import UserModel
+
+router = APIRouter(prefix="/otcm_user_agent", tags=["csai agents"])
+
+logger = logging.getLogger("pyxecm_api.agents.otcm_user_agent")
+
+
+@router.post(
+    "/user",
+    summary="Find a user by name or user attributes",
+    responses={
+        200: {"description": "User found"},
+        403: {"description": "Invalid credentials"},
+        400: {"description": "User not found"},
+    },
+    response_model=UserModel,
+    response_description="Details about a user. Best presented as a table with each user property in a row.",
+)
+def otcm_user_agent_find_user(
+    otcs: Annotated[OTCS, Depends(get_otcs_object_from_otcsticket)],
+    user: Annotated[UserModel, Body()],
+) -> UserModel | None:
+    """Find a user by by its name or other attributes.
+
+    The user ID, the user name (login), user first name, user last name and user email will be returned.
+    When a user is returned, display the user data as a markdown table.
+    """
+
+    response = otcs.get_users(
+        where_name=user.login,
+        where_first_name=user.first_name,
+        where_last_name=user.last_name,
+        where_business_email=user.email,
+    )
+
+    if not response or not response["results"]:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+
+    try:
+        department_id = otcs.get_result_value(response=response, key="group_id")
+        department = otcs.get_group(group_id=department_id) if department_id else None
+        department_name = otcs.get_result_value(response=department, key="name") if department else None
+        return UserModel(
+            user_id=otcs.get_result_value(response=response, key="id"),
+            login=otcs.get_result_value(response=response, key="name"),
+            first_name=otcs.get_result_value(response=response, key="first_name"),
+            last_name=otcs.get_result_value(response=response, key="last_name"),
+            email=otcs.get_result_value(response=response, key="business_email"),
+            department=department_name,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found") from e
+
+
+# end function definition

pyxecm_api/agents/otcm_workspace_agent/models.py

@@ -0,0 +1,40 @@
+"""Define Models for workspaces."""
+
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field
+
+
+class WorkspaceAttributeModel(BaseModel):
+    """Model for a workspace attribute."""
+
+    category: Annotated[str, Field(description="Category for the workspace attributes")]
+    attribute: Annotated[str, Field(description="Name of the attribute")]
+    value: Annotated[str, Field(description="Value of the attribute")]
+    set: Annotated[str, Field(description="Optional attribute group or set name")]
+
+
+class WorkspaceModel(BaseModel):
+    """Defines Model for describing workspaces in OTCM (Opentext Content Management).
+
+    To display an instance of this model, please display the link.
+    """
+
+    id: Annotated[int, Field(description="ID of the workspace")] = None
+    name: Annotated[str, Field(description="Name of the workspace")] = None
+    type: Annotated[str, Field(description="Name of the workspace type")] = None
+    description: Annotated[str, Field(description="Description of the workspace")] = None
+
+    link: Annotated[str, Field(description="Link to the workspace, should be used when the instance is displayed")] = (
+        None
+    )
+
+    # attributes: Annotated[
+    #     list[WorkspaceAttributeModel] | None,
+    #     Body(description="List of custom attributes associated with the workspace"),
+    # ] = None
+
+    def model_post_init(self, context: Any) -> None:  # noqa: ARG002, ANN401
+        """Post model initialization."""
+        # this could also be done with `default_factory`:
+        self.link = f"[{self.name}](/cs/cs/app/nodes/{self.id})"

pyxecm_api/agents/otcm_workspace_agent/router.py

@@ -0,0 +1,200 @@
+"""Define router for workspace endpoints."""
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Body, Depends, HTTPException, status
+from pyxecm.otcs import OTCS
+
+from pyxecm_api.agents.models import Context
+from pyxecm_api.common.functions import get_otcs_object_from_otcsticket
+
+from .models import WorkspaceModel
+
+router = APIRouter(prefix="/otcm_workspace_agent", tags=["csai agents"])
+
+logger = logging.getLogger("pyxecm_api.agents.otcm_workspace_agent")
+
+
+@router.post(
+    path="/find_workspace",
+    response_model=WorkspaceModel,
+    summary="Find the markdown link to a workspace by workspace name and workspace type and display the link.",
+    responses={
+        200: {"description": "Workspace found"},
+        403: {"description": "Invalid credentials"},
+        404: {"description": "Workspace not found"},
+    },
+)
+def otcm_workspace_agent_find_workspace(
+    context: Context,
+    otcs: Annotated[OTCS, Depends(get_otcs_object_from_otcsticket)],
+    workspace: Annotated[WorkspaceModel, Body()],
+) -> WorkspaceModel | None:
+    """Find a workspace by workspace name and workspace type.
+
+    The returned workspace is an OTCS workspace object. Show the markdown link in the chat response, sothat the user can click on it.
+    """
+
+    logger.info("Got context -> %s", context)
+
+    response = otcs.get_workspace_by_type_and_name(type_name=workspace.type, name="contains_" + workspace.name)
+
+    if response and len(response["results"]) == 1:
+        result = WorkspaceModel(
+            id=otcs.get_result_value(response=response, key="id"),
+            name=otcs.get_result_value(response=response, key="name"),
+            type=workspace.type,
+        )
+        logger.info("Workspace found -> %s", result)
+        return result
+
+    if response is None or not response["results"]:
+        response = otcs.search(search_term=workspace.name)
+
+    if response is None or not response["results"]:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Workspace not found.",
+        )
+
+    try:
+        return WorkspaceModel(
+            id=otcs.get_result_value(response=response, key="id"),
+            name=otcs.get_result_value(response=response, key="name"),
+            type=workspace.type,
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Workspace not found.",
+        ) from e
+
+
+# end function definition
+
+
+@router.post(
+    path="/lookup_workspace",
+    response_model=WorkspaceModel,
+    summary="Lookup a workspace based on its type and a value of one of the workspace attributes.",
+    responses={
+        200: {"description": "Workspace found"},
+        403: {"description": "Invalid credentials"},
+        400: {"description": "Workspace not found"},
+    },
+)
+def otcm_workspace_agent_lookup_workspace(
+    otcs: Annotated[OTCS, Depends(get_otcs_object_from_otcsticket)],
+    workspace: Annotated[WorkspaceModel, Body()],
+) -> WorkspaceModel | None:
+    """Lookup a workspace based on its type and a value of one of the workspace attributes.
+
+    Use this tool if the workspace name is _not_ specified but the user asks for a specific
+    workspace attribute value like cities, products, or other attributes.
+
+    Return the workspace data if it is found. If it is not found confirm with the user if the workspace should be created or not.
+    If it should be created call the tool: otcm_workspace_agent_create_workspace
+    """
+
+    # otcs._otcs_ticket = otcsticket
+
+    workspace_attributes = workspace.attributes or {}
+    if not workspace_attributes:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Workspace attributes must be provided for lookup.",
+        )
+
+    category = next((attr.category for attr in workspace_attributes if attr.category), None)
+    attribute = next((attr.attribute for attr in workspace_attributes if attr.attribute), None)
+    attribute_set = next((attr.set for attr in workspace_attributes if attr.set), None)
+    value = next((attr.value for attr in workspace_attributes if attr.value), None)
+
+    response = otcs.lookup_workspace(
+        type_name=workspace.type, category=category, attribute=attribute, attribute_set=attribute_set, value=value
+    )
+    if response is None or not response["results"]:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="No workspace of type -> '{}' with attribute -> '{}'{} and value -> '{}' found!".format(
+                workspace.type, attribute, " (set -> {})".format(attribute_set), value
+            ),
+        )
+
+    try:
+        return WorkspaceModel(
+            id=otcs.get_result_value(response=response, key="id"),
+            name=otcs.get_result_value(response=response, key="name"),
+            type=workspace.type,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Workspace not found") from e
+
+
+# end function definition
+
+
+@router.post(
+    path="/create_workspace",
+    response_model=WorkspaceModel,
+    summary="Create a workspace with given workspace name and workspace type and display the link.",
+    responses={
+        200: {"description": "Workspace created"},
+        403: {"description": "Invalid credentials"},
+        404: {"description": "Workspace creation failed"},
+    },
+)
+def otcm_workspace_agent_create_workspace(
+    otcs: Annotated[OTCS, Depends(get_otcs_object_from_otcsticket)],
+    workspace: Annotated[WorkspaceModel, Body()],
+) -> WorkspaceModel | None:
+    """Create a workspace with given workspace name and workspace type.
+
+    The ID of the created workspace, the final workspace name, and the workspace type will be returned.
+
+    """
+
+    workspace_type_id, workspace_templates = otcs.get_workspace_templates(type_name=workspace.type)
+    if workspace_type_id is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Workspace type -> '{}' not found!".format(workspace.type)
+        )
+    if not workspace_templates:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Workspace type -> '{}' has no templates!".format(workspace.type),
+        )
+
+    workspace_template_id = workspace_templates[0].get("id")
+
+    response = otcs.create_workspace(
+        workspace_template_id=workspace_template_id,
+        workspace_type=workspace_type_id,
+        workspace_name=workspace.name,
+        workspace_description="",
+    )
+
+    if response is None or not response["results"]:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Failed to create workspace -> '{}'".format(workspace.name)
+        )
+
+    try:
+        workspace_id = response.get("results", {}).get("id")
+
+        # The resulting workspace name can be different from the given name,
+        # so we need to fetch the workspace details again to get the final name.
+        response = otcs.get_workspace(node_id=workspace_id)
+        workspace_name = otcs.get_result_value(response=response, key="name")
+
+        return WorkspaceModel(
+            id=workspace_id,
+            name=workspace_name,
+            type=workspace.type,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Workspace not found") from e
+
+
+# end function definition

pyxecm_api/app.py

@@ -0,0 +1,221 @@
+"""API Implemenation for the Customizer to start and control the payload processing."""
+
+__author__ = "Dr. Marc Diefenbruch"
+__copyright__ = "Copyright (C) 2024-2025, OpenText"
+__credits__ = ["Kai-Philip Gatzweiler"]
+__maintainer__ = "Dr. Marc Diefenbruch"
+__email__ = "mdiefenb@opentext.com"
+
+import logging
+import os
+import threading
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from importlib.metadata import version
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+from prometheus_fastapi_instrumentator import Instrumentator
+from pyxecm.helper.otel_config import tracer
+from pyxecm_maintenance_page import run_maintenance_page
+
+from .agents.app import agent_routers
+from .agents.functions import register_all
+from .agents.otcm_knowledgegraph.functions import build_graph
+from .auth.router import router as auth_router
+from .common.functions import PAYLOAD_LIST
+from .common.metrics import payload_logs_by_payload, payload_logs_total
+from .common.router import router as common_router
+from .settings import api_settings
+from .terminal.router import router as terminal_router
+from .v1_csai.router import router as v1_csai_router
+from .v1_maintenance.router import router as v1_maintenance_router
+from .v1_otcs.router import router as v1_otcs_router
+from .v1_payload.functions import import_payload
+from .v1_payload.router import router as v1_payload_router
+
+logger = logging.getLogger("CustomizerAPI")
+
+
+# Check if Logfile and folder exists and is unique
+if os.path.isfile(os.path.join(api_settings.logfolder, api_settings.logfile)):
+    customizer_start_time = datetime.now(UTC).strftime(
+        "%Y-%m-%d_%H-%M",
+    )
+    api_settings.logfile = f"customizer_{customizer_start_time}.log"
+elif not os.path.exists(api_settings.logfolder):
+    os.makedirs(api_settings.logfolder)
+
+handlers = [logging.FileHandler(os.path.join(api_settings.logfolder, api_settings.logfile))]
+if api_settings.log_payload_processing:
+    handlers.append(logging.StreamHandler())
+
+logging.basicConfig(
+    format="%(asctime)s %(levelname)s [%(name)s] [%(threadName)s] %(message)s",
+    datefmt="%d-%b-%Y %H:%M:%S",
+    level=api_settings.loglevel,
+    handlers=handlers,
+)
+
+
+@asynccontextmanager
+async def lifespan(
+    app: FastAPI,  # noqa: ARG001
+) -> AsyncGenerator:
+    """Lifespan Method for FASTAPI to handle the startup and shutdown process.
+
+    Args:
+        app (FastAPI):
+            The application.
+
+    """
+
+    logger.debug("Settings -> %s", api_settings)
+
+    with tracer.start_as_current_span("import_payloads"):
+        if api_settings.import_payload:
+            logger.info("Importing filesystem payloads...")
+
+            # Base Payload
+            import_payload(payload=api_settings.payload)
+
+            # External Payload
+            import_payload(payload_dir=api_settings.payload_dir, dependencies=True)
+
+            # Optional Payload
+            import_payload(payload_dir=api_settings.payload_dir_optional)
+
+    logger.info("Starting maintenance_page thread...")
+    if api_settings.maintenance_page:
+        run_maintenance_page()
+
+    if api_settings.csai_studio_integration:
+        logger.info("Registering Content Aviator tools...")
+        register_all()
+        threading.Thread(name="KnowledgeGraph", target=build_graph).start()
+
+    yield
+    logger.info("Shutdown")
+    PAYLOAD_LIST.stop_payload_processing()
+
+
+app = FastAPI(
+    docs_url="/api",
+    title=api_settings.title,
+    description=api_settings.description,
+    openapi_url=api_settings.openapi_url,
+    root_path=api_settings.root_path,
+    lifespan=lifespan,
+    version=version("pyxecm"),
+    openapi_tags=[
+        {
+            "name": "auth",
+            "description": "Authentication Endpoint - Users are authenticated against Opentext Directory Services",
+        },
+        {
+            "name": "payload",
+            "description": "Get status and manipulate payload objects ",
+        },
+        {
+            "name": "maintenance",
+            "description": "Enable, disable or alter the maintenance mode.",
+        },
+    ],
+)
+
+FastAPIInstrumentor.instrument_app(app)
+
+## Add Middlewares
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=api_settings.trusted_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+## Add all Routers
+app.include_router(router=common_router)
+app.include_router(router=auth_router)
+app.include_router(router=v1_maintenance_router)
+app.include_router(router=v1_otcs_router)
+app.include_router(router=v1_payload_router)
+
+if api_settings.ws_terminal:
+    app.include_router(router=terminal_router)
+
+if api_settings.csai:
+    app.mount(
+        "/api/v1/csai/lib",
+        StaticFiles(packages=["pyxecm_api.v1_csai"]),
+        name="csai-statics",
+    )
+
+    app.include_router(router=v1_csai_router)
+    for agent_router in agent_routers:
+        app.include_router(prefix="/agents", router=agent_router)
+
+
+## Add Prometheus Instrumentator for /metrics,
+if api_settings.metrics:
+    # Add Prometheus Instrumentator for /metricsf
+    instrumentator = Instrumentator().instrument(app).expose(app)
+    instrumentator.add(payload_logs_by_payload(PAYLOAD_LIST))
+    instrumentator.add(payload_logs_total(PAYLOAD_LIST))
+
+
+## Start the API Server
+def run_api() -> None:
+    """Start the FASTAPI Webserver."""
+
+    # Check if Temp and Log dir exists
+    if not os.path.exists(api_settings.temp_dir):
+        os.makedirs(api_settings.temp_dir)
+    if not os.path.exists(api_settings.logfolder):
+        os.makedirs(api_settings.logfolder)
+
+    # Check if Logfile and exists and is unique
+    if os.path.isfile(os.path.join(api_settings.logfolder, api_settings.logfile)):
+        customizer_start_time = datetime.now(UTC).strftime(
+            "%Y-%m-%d_%H-%M",
+        )
+        api_settings.logfile = f"customizer_{customizer_start_time}.log"
+
+    # Configure Logging for uvicorn
+    log_config = uvicorn.config.LOGGING_CONFIG
+
+    # Stdout
+    log_config["formatters"]["pyxecm"] = {
+        "()": "uvicorn.logging.DefaultFormatter",
+        "fmt": "%(levelprefix)s [%(name)s] [%(threadName)s] %(message)s",
+        "use_colors": True,
+    }
+    log_config["handlers"]["pyxecm"] = {
+        "formatter": "pyxecm",
+        "class": "logging.StreamHandler",
+        "stream": "ext://sys.stdout",
+    }
+
+    log_config["loggers"]["pyxecm"] = {
+        "handlers": ["pyxecm"],
+        "level": api_settings.loglevel,
+        "propagate": False,
+    }
+
+    logger.info("Starting processing thread...")
+    PAYLOAD_LIST.run_payload_processing(concurrent=api_settings.concurrent_payloads)
+
+    uvicorn.run(
+        "pyxecm_api:app",
+        host=api_settings.bind_address,
+        port=api_settings.bind_port,
+        workers=api_settings.workers,
+        reload=api_settings.reload,
+        proxy_headers=True,
+        forwarded_allow_ips="*",
+        log_config=log_config,
+    )

{pyxecm/customizer/api → pyxecm_api}/auth/functions.py

@@ -7,8 +7,9 @@ import requests
 from fastapi import APIRouter, Depends, HTTPException, status
 from fastapi.security import APIKeyHeader, OAuth2PasswordBearer
 
-from pyxecm.customizer.api.auth.models import User
-from pyxecm.customizer.api.settings import api_settings
+from pyxecm_api.settings import api_settings
+
+from .models import User
 
 router = APIRouter()
 
@@ -19,6 +20,7 @@ oauth2_scheme = OAuth2PasswordBearer(
     scheme_name="OTDS Authentication",
 )
 apikey_header = APIKeyHeader(name="x-api-key", auto_error=False, scheme_name="APIKey")
+otcsticket = APIKeyHeader(name="otcsticket", auto_error=True, scheme_name="OTCSTicket")
 
 
 def get_groups(response: dict, token: str) -> list:
@@ -97,3 +99,9 @@ async def get_authorized_user(current_user: Annotated[User, Depends(get_current_
             detail=f"User {current_user.id} is not authorized",
         )
     return current_user
+
+
+async def get_otcsticket(otcsticket: Annotated[str, Depends(otcsticket)]) -> User:
+    """Check if the user is authorized (member of the Group otadmin@otds.admin)."""
+
+    return otcsticket

{pyxecm/customizer/api → pyxecm_api}/auth/router.py

@@ -8,9 +8,10 @@ from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import JSONResponse
 from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
 
-from pyxecm.customizer.api.auth.functions import get_current_user
-from pyxecm.customizer.api.auth.models import User
-from pyxecm.customizer.api.settings import api_settings
+from pyxecm_api.settings import api_settings
+
+from .functions import get_current_user
+from .models import User
 
 router = APIRouter()