fix: package agent as proper python module

athewsey · athewsey · commit 67c06253e46c · 2025-09-23T23:21:13.000+08:00
Previously, we ran with src/ as the working directory and hacked
PYTHONPATH to resolve local dependencies. Instead, make the
cx-agent-backend a buildable Python package with a runnable
entrypoint.
diff --git a/cx-agent-backend/Dockerfile b/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"]
diff --git a/cx-agent-backend/cx_agent_backend/__init__.py b/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,
+)
diff --git a/cx-agent-backend/cx_agent_backend/__main__.py b/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(),
+)
diff --git a/cx-agent-backend/cx_agent_backend/domain/__init__.py b/cx-agent-backend/cx_agent_backend/domain/__init__.py
@@ -0,0 +1 @@
+"""Domain layer"""
diff --git a/cx-agent-backend/cx_agent_backend/domain/entities/conversation.py b/cx-agent-backend/cx_agent_backend/domain/entities/conversation.py
diff --git a/cx-agent-backend/cx_agent_backend/domain/ports/secret_reader.py b/cx-agent-backend/cx_agent_backend/domain/ports/secret_reader.py
diff --git a/cx-agent-backend/cx_agent_backend/domain/repositories/conversation_repository.py b/cx-agent-backend/cx_agent_backend/domain/repositories/conversation_repository.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):
diff --git a/cx-agent-backend/cx_agent_backend/domain/services/agent_service.py b/cx-agent-backend/cx_agent_backend/domain/services/agent_service.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):
diff --git a/cx-agent-backend/cx_agent_backend/domain/services/conversation_service.py b/cx-agent-backend/cx_agent_backend/domain/services/conversation_service.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__)
 
diff --git a/cx-agent-backend/cx_agent_backend/domain/services/guardrail_service.py b/cx-agent-backend/cx_agent_backend/domain/services/guardrail_service.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 GuardrailAssessment(str, Enum):
diff --git a/cx-agent-backend/cx_agent_backend/domain/services/llm_service.py b/cx-agent-backend/cx_agent_backend/domain/services/llm_service.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 ModelProvider(str, Enum):
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/__init__.py b/cx-agent-backend/cx_agent_backend/infrastructure/__init__.py
@@ -0,0 +1 @@
+"""Infrastructure layer"""
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/adapters/bedrock_guardrail_service.py b/cx-agent-backend/cx_agent_backend/infrastructure/adapters/bedrock_guardrail_service.py
@@ -3,8 +3,8 @@
 import boto3
 import structlog
 
-from domain.entities.conversation import Message
-from domain.services.guardrail_service import (
+from cx_agent_backend.domain.entities.conversation import Message
+from cx_agent_backend.domain.services.guardrail_service import (
     GuardrailAssessment,
     GuardrailResult,
     GuardrailService,
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/adapters/langgraph_agent_service.py b/cx-agent-backend/cx_agent_backend/infrastructure/adapters/langgraph_agent_service.py
@@ -10,16 +10,16 @@
 
 logger = logging.getLogger(__name__)
 
-from domain.entities.conversation import Message, MessageRole
-from domain.services.agent_service import (
+from cx_agent_backend.domain.entities.conversation import Message, MessageRole
+from cx_agent_backend.domain.services.agent_service import (
     AgentRequest,
     AgentResponse,
     AgentService,
     AgentType,
 )
-from domain.services.guardrail_service import GuardrailAssessment, GuardrailService
-from domain.services.llm_service import LLMService
-from infrastructure.adapters.tools import tools
+from cx_agent_backend.domain.services.guardrail_service import GuardrailAssessment, GuardrailService
+from cx_agent_backend.domain.services.llm_service import LLMService
+from cx_agent_backend.infrastructure.adapters.tools import tools
 
 
 class LangGraphAgentService(AgentService):
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/adapters/memory_conversation_repository.py b/cx-agent-backend/cx_agent_backend/infrastructure/adapters/memory_conversation_repository.py
@@ -2,8 +2,8 @@
 
 from uuid import UUID
 
-from domain.entities.conversation import Conversation
-from domain.repositories.conversation_repository import ConversationRepository
+from cx_agent_backend.domain.entities.conversation import Conversation
+from cx_agent_backend.domain.repositories.conversation_repository import ConversationRepository
 
 
 class MemoryConversationRepository(ConversationRepository):
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/adapters/openai_llm_service.py b/cx-agent-backend/cx_agent_backend/infrastructure/adapters/openai_llm_service.py
@@ -3,8 +3,8 @@
 from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
 from langchain_openai import ChatOpenAI
 
-from domain.entities.conversation import MessageRole
-from domain.services.llm_service import LLMRequest, LLMResponse, LLMService
+from cx_agent_backend.domain.entities.conversation import MessageRole
+from cx_agent_backend.domain.services.llm_service import LLMRequest, LLMResponse, LLMService
 
 
 class OpenAILLMService(LLMService):
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/adapters/sql_alchemy_conversation_service.py b/cx-agent-backend/cx_agent_backend/infrastructure/adapters/sql_alchemy_conversation_service.py
@@ -1,13 +1,15 @@
 # infrastructure/sqlalchemy_conversation_repository.py
-from domain.repositories.conversation_repository import ConversationRepository
-from domain.entities.conversation import Conversation, Message
+import uuid
+
 from sqlalchemy.orm import Session
-from presentation.schemas.conversation_schemas import (
+
+from cx_agent_backend.domain.repositories.conversation_repository import ConversationRepository
+from cx_agent_backend.domain.entities.conversation import Conversation, Message
+from cx_agent_backend.presentation.schemas.conversation_schemas import (
     ConversationSchema,
     MessageSchema,
     ConversationUserDB,
 )  # your SQLAlchemy models
-import uuid
 
 
 class SQLAlchemyConversationRepository(ConversationRepository):
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/adapters/tools.py b/cx-agent-backend/cx_agent_backend/infrastructure/adapters/tools.py
@@ -6,9 +6,9 @@
 import logging
 import json
 
-from infrastructure.config.settings import settings
-from infrastructure.aws.secret_reader import AWSSecretsReader
-from infrastructure.aws.parameter_store_reader import AWSParameterStoreReader
+from cx_agent_backend.infrastructure.config.settings import settings
+from cx_agent_backend.infrastructure.aws.secret_reader import AWSSecretsReader
+from cx_agent_backend.infrastructure.aws.parameter_store_reader import AWSParameterStoreReader
 
 logger = logging.getLogger(__name__)
 
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/aws/parameter_store_reader.py b/cx-agent-backend/cx_agent_backend/infrastructure/aws/parameter_store_reader.py
@@ -1,6 +1,6 @@
 import boto3
 
-from infrastructure.config.settings import settings
+from cx_agent_backend.infrastructure.config.settings import settings
 
 
 class AWSParameterStoreReader:
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/aws/secret_reader.py b/cx-agent-backend/cx_agent_backend/infrastructure/aws/secret_reader.py
@@ -1,7 +1,7 @@
 import boto3
 
-from domain.ports.secret_reader import SecretReader
-from infrastructure.config.settings import settings
+from cx_agent_backend.domain.ports.secret_reader import SecretReader
+from cx_agent_backend.infrastructure.config.settings import settings
 
 class AWSSecretsReader(SecretReader):
     def read_secret(self, name: str) -> str:
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/config/container.py b/cx-agent-backend/cx_agent_backend/infrastructure/config/container.py
@@ -3,16 +3,16 @@
 import json
 from dependency_injector import containers, providers
 
-from domain.services.conversation_service import ConversationService
-from infrastructure.adapters.memory_conversation_repository import (
+from cx_agent_backend.domain.services.conversation_service import ConversationService
+from cx_agent_backend.infrastructure.adapters.memory_conversation_repository import (
     MemoryConversationRepository,
 )
-from infrastructure.adapters.langgraph_agent_service import LangGraphAgentService
-from infrastructure.adapters.bedrock_guardrail_service import BedrockGuardrailService
-from infrastructure.adapters.openai_llm_service import OpenAILLMService
-from infrastructure.config.settings import settings
-from infrastructure.aws.secret_reader import AWSSecretsReader
-from infrastructure.aws.parameter_store_reader import AWSParameterStoreReader
+from cx_agent_backend.infrastructure.adapters.langgraph_agent_service import LangGraphAgentService
+from cx_agent_backend.infrastructure.adapters.bedrock_guardrail_service import BedrockGuardrailService
+from cx_agent_backend.infrastructure.adapters.openai_llm_service import OpenAILLMService
+from cx_agent_backend.infrastructure.config.settings import settings
+from cx_agent_backend.infrastructure.aws.secret_reader import AWSSecretsReader
+from cx_agent_backend.infrastructure.aws.parameter_store_reader import AWSParameterStoreReader
 
 
 class Container(containers.DeclarativeContainer):
diff --git a/cx-agent-backend/cx_agent_backend/infrastructure/config/settings.py b/cx-agent-backend/cx_agent_backend/infrastructure/config/settings.py
diff --git a/cx-agent-backend/cx_agent_backend/presentation/__init__.py b/cx-agent-backend/cx_agent_backend/presentation/__init__.py
@@ -0,0 +1 @@
+"""Presentation layer"""
diff --git a/cx-agent-backend/cx_agent_backend/presentation/api/conversation_router.py b/cx-agent-backend/cx_agent_backend/presentation/api/conversation_router.py
@@ -5,19 +5,18 @@
 from dependency_injector.wiring import Provide, inject
 from fastapi import APIRouter, Depends, HTTPException, status
 
-from domain.entities.conversation import Conversation, Message
-from domain.services.conversation_service import ConversationService
-from infrastructure.config.container import Container
-from presentation.schemas.conversation_schemas import (
+from cx_agent_backend.domain.entities.conversation import Conversation, Message
+from cx_agent_backend.domain.services.conversation_service import ConversationService
+from cx_agent_backend.infrastructure.config.container import Container
+from cx_agent_backend.presentation.schemas.conversation_schemas import (
     ConversationSchema,
     CreateConversationRequest,
+    HealthResponse,
     MessageSchema,
     SendMessageRequest,
     SendMessageResponse,
 )
 
-from presentation.schemas.conversation_schemas import HealthResponse
-
 router = APIRouter(prefix="/api/v1", tags=["conversations"])
 
 
diff --git a/cx-agent-backend/cx_agent_backend/presentation/schemas/conversation_schemas.py b/cx-agent-backend/cx_agent_backend/presentation/schemas/conversation_schemas.py
diff --git a/cx-agent-backend/cx_agent_backend/server.py b/cx-agent-backend/cx_agent_backend/server.py
@@ -1,29 +1,19 @@
-"""FastAPI application entry point."""
+"""FastAPI application definition"""
 
-import structlog
-from fastapi import FastAPI, Request
+from datetime import datetime
+import time
 
-from infrastructure.config.container import Container
-from infrastructure.config.settings import settings
-from presentation.api.conversation_router import router as conversation_router
+from fastapi import FastAPI, HTTPException, Request
+import structlog
 
-# Configure structured logging
-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,
+from cx_agent_backend.infrastructure.config.container import Container
+from cx_agent_backend.infrastructure.config.settings import settings
+from cx_agent_backend.presentation.api.conversation_router import (
+    router as conversation_router,
+    send_message
 )
+from cx_agent_backend.presentation.schemas.conversation_schemas import SendMessageRequest
+
 
 logger = structlog.get_logger()
 
@@ -44,7 +34,7 @@ def create_app() -> FastAPI:
     # Wire container
     container.wire(
         modules=[
-            "presentation.api.conversation_router",
+            "cx_agent_backend.presentation.api.conversation_router",
         ]
     )
 
@@ -54,15 +44,13 @@ def create_app() -> FastAPI:
     # Add AgentCore-compliant endpoints directly to app
     @app.get("/ping")
     async def ping():
-        import time
+        """Container health check endpoint"""
+        
         return {"status": "Healthy", "time_of_last_update": int(time.time())}
     
     @app.post("/invocations")
     async def invocations(request: dict, http_request: Request):
-        from fastapi import HTTPException
-        from presentation.api.conversation_router import send_message
-        from presentation.schemas.conversation_schemas import SendMessageRequest
-        from datetime import datetime
+        """AgentCore-compatible endpoint to invoke the agent (send message & get response)"""
         
         # Extract session information
         session_id = http_request.headers.get("x-amzn-bedrock-agentcore-runtime-session-id", "N/A")
@@ -101,6 +89,3 @@ async def invocations(request: dict, http_request: Request):
     logger.info("Application created", settings=settings.model_dump())
 
     return app
-
-
-app = create_app()
diff --git a/cx-agent-backend/pyproject.toml b/cx-agent-backend/pyproject.toml
@@ -1,7 +1,7 @@
 [project]
 name = "cx-agent-backend"
 version = "0.1.0"
-description = "Clean Architecture CX Agent Backend"
+description = "Customer service demo agent compatible with Bedrock AgentCore"
 requires-python = ">=3.11"
 dependencies = [
     "aws-opentelemetry-distro>=0.1.0",
@@ -36,7 +36,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src"]
+packages = ["cx_agent_backend"]
 
 [tool.ruff]
 target-version = "py311"
diff --git a/cx-agent-backend/src/domain/__init__.py b/cx-agent-backend/src/domain/__init__.py
diff --git a/cx-agent-backend/src/infrastructure/__init__.py b/cx-agent-backend/src/infrastructure/__init__.py
diff --git a/cx-agent-backend/src/presentation/__init__.py b/cx-agent-backend/src/presentation/__init__.py
diff --git a/cx-agent-backend/src/run.py b/cx-agent-backend/src/run.py
