Client
  └─► FastAPI Server (Port 6000)
        └─► Hayley Chat Adapter
              ├─► Hayley Engine (ML/NLP)
              ├─► Translate to Human (Spanish)
              ├─► Agent Handoff Service
              └─► GraphQL API (Message Persistence)

hayley-chat-adapter-microservice/
├── app.py                        ← FastAPI entrypoint, endpoints, Langfuse init
├── config.yaml                   ← Environment-specific service URLs
├── requirements.txt              ← Python dependencies
├── Dockerfile                    ← Docker build (exposes port 6000)
├── .env                          ← Secrets and environment variables
│
├── bean/
│   └── chat_adapter_response.py ← Pydantic response model
│
├── utils/
│   ├── chat_adapter.py          ← Core orchestration logic
│   ├── utils.py                 ← GraphQL, caching, contact extraction
│   ├── arguments.py             ← Constants and defaults
│   └── constants.py             ← System-wide constants
│
└── deployments/
    ├── qa/Jenkinsfile
    ├── stg/Jenkinsfile
    └── prod/Jenkinsfile

1.  POST /chat_adapter received
2.  Pydantic validates request          → 400 on failure
3.  Trim history to last 4 messages
4.  Call Hayley Engine
5.  Format response by retrieval_type:
      "node" + "neighborhood_summary"  → verbose response
      "node"                           → format_node_response_to_markdown()
      "rag|fixed|adapter|spf"          → concise response
6.  Extract contact info (if sub_intent matches)
7.  createHayleyMessage [question] via GraphQL
8.  Fire async agent handoff (non-blocking)
9.  createHayleyMessage [answer] via GraphQL
10. Return assembled response with trace_id

{
  "propertyId": "1234567890123456789",
  "message": "Show me available 2-bedroom apartments",
  "orgId": "9876543210987654321",
  "session_id": "aaaabbbbccccddddeeeeffffgggghhhh",
  "conversation_id": "1111111111111111111",
  "graphql_api_key": "Rjp3U6OfhyuxMVSYHCJErDlFeZamWs5QwIX4dKik",
  "tourScheduleEnabled": true,
  "history": [
    { "role": "user", "content": "Hello" },
    { "role": "assistant", "content": "Hi! How can I help?" }
  ],
  "entry_id": "optional-entry-id",
  "booking_id": "optional-booking-id",
  "reschedule_information": {},
  "schedule_information": {},
  "spanish_support_enabled": false,
  "spanish_toggle": false,
  "is_first_entry": false
}

{
  "response": "Here are available 2-bedroom units at...",
  "intent": "property_search",
  "sub_intent": "unit_availability",
  "message_id": "1709542253522009420",
  "retrieval_type": "node",
  "orchestrator_level1_details": {},
  "orchestrator_level2_details": {},
  "keyword_cache": { "bedrooms": 2 },
  "not_available": [],
  "context": null,
  "follow_up": "Would you like to schedule a tour?",
  "latency": {
    "hayley_engine_latency": 1234,
    "chat_adapter_latency": 2456,
    "extract_and_update_contact_latency": 45,
    "create_message_latency": 312
  },
  "language": "en",
  "agent_handoff": null,
  "memory": null,
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

// 400 — Validation error
{ "detail": { "message": "Invalid propertyId format", "trace_id": "4bf92f35..." } }

// 500 — Internal error
{ "detail": { "message": "Unexpected error", "trace_id": "4bf92f35..." } }

// 503 — Downstream unavailable
{ "detail": "Service temporarily unavailable" }

# Deployment target
ENVIRONMENT="qa|staging|prod"

# Langfuse — LLM Observability
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_BASE_URL="https://langfuse.hyly.us"
LANGFUSE_DEBUG="false"

# GraphQL API Keys (per environment)
graphql_api_key="..."          # QA
graphql_api_key_stg="..."      # Staging
graphql_api_key_prod="..."     # Prod

# GraphQL Endpoint URLs
GRAPHQL_QA_URL="https://qa.hyly.us/graphql"
GRAPHQL_STG_URL="https://my.hyly.us/graphql"
GRAPHQL_PROD_URL="https://my.hy.ly/graphql"

# GraphQL Authorization Headers
GRAPHQL_KEY_QA="userid___1709542253522009420"
GRAPHQL_KEY_STAGING="userid___1777464981952577365"
GRAPHQL_KEY_PROD="myhyly-hyblast-sync"

# Tracing
DISABLE_TRACING="false"

pip install -r requirements.txt
export ENVIRONMENT=qa
uvicorn app:app --reload --host 0.0.0.0 --port 6000

docker build -t hayley-chat-adapter .
docker run -p 6000:6000 --env-file .env hayley-chat-adapter