Merge #7 package agent as Python module

Run the agent as a Python package/module with an entrypoint, rather
than a collection of scripts with PYTHONPATH=src

Author: athewsey

README.md

@@ -78,8 +78,7 @@ uv sync --all-extras --frozen
 ```
 2. **Run locally**: 
 ```bash
-cd src
-uv run run.py
+uv run python -m cx_agent_backend
 ```
 3. **Test the health endpoint**:
 ```bash

cx-agent-backend/Dockerfile

@@ -8,18 +8,16 @@ WORKDIR /app
 ENV UV_PROJECT_ENVIRONMENT="/usr/local/"
 ENV UV_COMPILE_BYTECODE=1
 
-# Copy dependency configuration and install Python dependencies
-COPY pyproject.toml .
-RUN uv sync
+# Install dependencies only (so this step can be cached if only source files are changed):
+COPY pyproject.toml uv.lock ./
+RUN uv sync --no-dev --no-install-local
 
-# Copy application source code
-COPY src/ ./src/
-
-# Set Python path
-ENV PYTHONPATH="/app/src"
+# Copy and install the agent source code itself:
+COPY cx_agent_backend ./cx_agent_backend
+RUN uv sync --no-dev
 
 # Expose FastAPI server port
 EXPOSE 8080
 
 # Start the CX Agent service
-CMD ["opentelemetry-instrument", "python", "src/run.py"]
+CMD ["opentelemetry-instrument", "python", "-m", "cx_agent_backend"]

cx-agent-backend/cx_agent_backend/__init__.py

@@ -0,0 +1,22 @@
+"""CX demo agent package including agent definition and AgentCore-compatible REST server"""
+
+# Configure structured logging here during module initialization, before other local and external
+# imports start creating loggers:
+import structlog
+
+structlog.configure(
+    processors=[
+        structlog.stdlib.filter_by_level,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+        structlog.processors.UnicodeDecoder(),
+        structlog.processors.JSONRenderer(),
+    ],
+    context_class=dict,
+    logger_factory=structlog.stdlib.LoggerFactory(),
+    cache_logger_on_first_use=True,
+)

cx-agent-backend/cx_agent_backend/__main__.py

@@ -0,0 +1,14 @@
+"""Main entrypoint for running the agent server (uvicorn-fronted FastAPI)"""
+
+import uvicorn
+
+from cx_agent_backend.infrastructure.config.settings import settings
+from cx_agent_backend.server import create_app
+
+uvicorn.run(
+    create_app(),
+    host=settings.host,
+    port=settings.port,
+    reload=settings.debug,
+    log_level=settings.log_level.lower(),
+)

cx-agent-backend/cx_agent_backend/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain layer"""

…kend/src/domain/entities/conversation.py …_backend/domain/entities/conversation.pycx-agent-backend/src/domain/entities/conversation.py renamed to cx-agent-backend/cx_agent_backend/domain/entities/conversation.py cx-agent-backend/src/domain/entities/conversation.py renamed to cx-agent-backend/cx_agent_backend/domain/entities/conversation.py

@@ -3,7 +3,7 @@
 from abc import ABC, abstractmethod
 from uuid import UUID
 
-from domain.entities.conversation import Conversation
+from cx_agent_backend.domain.entities.conversation import Conversation
 
 
 class ConversationRepository(ABC):

…ackend/src/domain/ports/secret_reader.py …nt_backend/domain/ports/secret_reader.pycx-agent-backend/src/domain/ports/secret_reader.py renamed to cx-agent-backend/cx_agent_backend/domain/ports/secret_reader.py cx-agent-backend/src/domain/ports/secret_reader.py renamed to cx-agent-backend/cx_agent_backend/domain/ports/secret_reader.py

@@ -4,7 +4,7 @@
 from dataclasses import dataclass
 from enum import Enum
 
-from domain.entities.conversation import Message
+from cx_agent_backend.domain.entities.conversation import Message
 
 
 class AgentType(str, Enum):

…/repositories/conversation_repository.py …/repositories/conversation_repository.pycx-agent-backend/src/domain/repositories/conversation_repository.py renamed to cx-agent-backend/cx_agent_backend/domain/repositories/conversation_repository.py cx-agent-backend/src/domain/repositories/conversation_repository.py renamed to cx-agent-backend/cx_agent_backend/domain/repositories/conversation_repository.py

@@ -6,10 +6,10 @@
 
 from langfuse import get_client, Langfuse
 
-from domain.entities.conversation import Conversation, Message
-from domain.repositories.conversation_repository import ConversationRepository
-from domain.services.agent_service import AgentRequest, AgentService, AgentType
-from domain.services.guardrail_service import GuardrailAssessment, GuardrailService
+from cx_agent_backend.domain.entities.conversation import Conversation, Message
+from cx_agent_backend.domain.repositories.conversation_repository import ConversationRepository
+from cx_agent_backend.domain.services.agent_service import AgentRequest, AgentService, AgentType
+from cx_agent_backend.domain.services.guardrail_service import GuardrailAssessment, GuardrailService
 
 logger = logging.getLogger(__name__)