add Claude instructions and serve OpenAPI v3.0.1 spec for Azure API Management compatibility (#18)

* add Claude instructions and serve OpenAPI v3.0.1 spec for Azure API Management compatibility

* refactors

* fmt

Author: kelsey-wong

CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+TLM App is a standalone web application for serving the Trustworthy Language Model (TLM) using FastAPI. The main service is `chat-backend` which provides a REST API for chat functionality.
+
+## Development Commands
+
+### Running the Application Locally
+- **Setup**: Requires Docker, Tilt, and Kind
+- **Create cluster**: `kind create cluster --name tlm-app`
+- **Start development**: `tilt up`
+- **Access application**: http://localhost:8080
+- **API docs**: http://localhost:8080/api/docs
+
+### Testing Commands
+- **Run all tests**: `./scripts/dev/test.sh chat-backend`
+- **Run specific test**: `./scripts/dev/test.sh chat-backend tests/routers/test_chat.py`
+- **Run with debugger**: `./scripts/dev/test.sh chat-backend --pdb`
+- **Run with stdout**: `./scripts/dev/test.sh chat-backend -s`
+
+### Alternative Test Commands (via Makefile)
+- **Start test harness**: `make test-up`
+- **Run tests**: `make test-chat-backend`
+- **Stop test harness**: `make test-down`
+
+## Architecture
+
+### Core Stack
+- **FastAPI**: ASGI web framework with type annotations and auto-generated docs
+- **Pydantic**: Data validation and parsing
+- **uvicorn**: ASGI server for production
+- **Python 3.10+**: Required runtime
+
+### Service Structure
+The main service is in `services/chat-backend/` with:
+- `src/app.py`: Main FastAPI application entry point
+- `src/routers/`: API endpoint definitions (chat, health, main)
+- `src/schemas/`: Pydantic models for request/response validation
+- `src/services/`: Business logic (Azure integration, chat config, streaming)
+- `src/middleware/`: Request/response processing (audit logging)
+- `src/utils/`: Utilities (logging, models configuration)
+- `tests/`: Test suite with pytest and async support
+
+### Key Configuration
+- **Environment**: Copy `.env.example` to `.env` in service directories (values unquoted)
+- **TLM Core**: External dependency at version v0.0.39
+- **Code quality**: Ruff formatter (120 char line length), mypy type checking
+- **Test coverage**: Coverage reporting with pytest
+
+### Deployment
+- **Kubernetes**: Helm charts in `deploy/helm/`
+- **Container registry**: Uses Docker build with live updates via Tilt
+- **Infrastructure**: Terraform configs for Azure (AKS) and AWS (EKS)
+
+## Code Quality Tools
+- **Linting**: `ruff` (configured in pyproject.toml)
+- **Type checking**: `mypy` with Pydantic plugin
+- **Testing**: `pytest` with async support and recording for external calls
+- **SonarQube**: Automated code quality scanning (project: TLM-app)

services/chat-backend/src/app.py

@@ -3,22 +3,29 @@
 # setup logging, before importing anything else (and before creating other loggers)
 setup_logging()
 
+import json
 import logging
 
 from fastapi import FastAPI, Request, Response  # noqa: E402
 from fastapi.middleware.cors import CORSMiddleware  # noqa: E402
+from fastapi.responses import JSONResponse  # noqa: E402
 from fastapi.routing import APIRoute  # noqa: E402
 
 from src.core.config import get_settings  # noqa: E402
 from src.middleware import AuditMiddleware  # noqa: E402
 from src.routers.main import api_router  # noqa: E402
+from src.utils.openapi_converter import convert_openapi_spec  # noqa: E402
 
 config = get_settings()
 logger = logging.getLogger(__name__)
 
 
 def custom_generate_unique_id(route: APIRoute) -> str:
-    return f"{route.tags[0]}-{route.name}"
+    if route.tags and len(route.tags) > 0:
+        return f"{route.tags[0]}-{route.name}"
+    return route.name
+
+
 
 
 app = FastAPI(
@@ -40,6 +47,15 @@ def custom_generate_unique_id(route: APIRoute) -> str:
 app.include_router(api_router, prefix=config.API_PREFIX)
 
 
+# Add OpenAPI 3.0.1 compatible endpoint
+@app.get(f"{config.API_PREFIX}/openapi-3.0.1.json", include_in_schema=False)
+async def get_openapi_3_0_1():
+    """Get OpenAPI spec converted to 3.0.1 for compatibility."""
+    openapi_spec = app.openapi()
+    converted_spec = convert_openapi_spec(openapi_spec)
+    return JSONResponse(content=converted_spec)
+
+
 # Add logging on exceptions
 @app.exception_handler(Exception)
 async def exception_handler(request: Request, exc: Exception) -> Response:

services/chat-backend/src/utils/openapi_converter.py

@@ -0,0 +1,70 @@
+"""
+OpenAPI 3.1.0 to 3.0.1 converter utility.
+"""
+
+import json
+from typing import Any, Dict
+
+
+def convert_const_to_enum(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert OpenAPI 3.1 'const' to OpenAPI 3.0 'enum'."""
+    if isinstance(schema, dict):
+        if 'const' in schema:
+            schema['enum'] = [schema.pop('const')]
+        
+        # Recursively process nested schemas
+        for value in schema.values():
+            if isinstance(value, dict):
+                convert_const_to_enum(value)
+            elif isinstance(value, list):
+                for item in value:
+                    if isinstance(item, dict):
+                        convert_const_to_enum(item)
+    
+    return schema
+
+
+def convert_anyof_nullable(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert OpenAPI 3.1 anyOf nullable patterns to OpenAPI 3.0 nullable."""
+    if isinstance(schema, dict):
+        # Handle anyOf with null type pattern
+        if 'anyOf' in schema:
+            any_of = schema['anyOf']
+            # Check if this is a nullable pattern (has null type)
+            non_null_schemas = [s for s in any_of if s.get('type') != 'null']
+            null_schemas = [s for s in any_of if s.get('type') == 'null']
+            
+            if null_schemas and len(non_null_schemas) == 1:
+                # This is a nullable pattern, convert it
+                base_schema = non_null_schemas[0]
+                schema.update(base_schema)
+                schema['nullable'] = True
+                schema.pop('anyOf')
+        
+        # Recursively process nested schemas
+        for value in schema.values():
+            if isinstance(value, dict):
+                convert_anyof_nullable(value)
+            elif isinstance(value, list):
+                for item in value:
+                    if isinstance(item, dict):
+                        convert_anyof_nullable(item)
+    
+    return schema
+
+
+def convert_openapi_spec(spec: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert OpenAPI 3.1.0 spec to 3.0.1."""
+    # Make a copy to avoid modifying the original
+    converted_spec = json.loads(json.dumps(spec))
+    
+    # Change version
+    converted_spec['openapi'] = '3.0.1'
+    
+    # Convert const to enum
+    convert_const_to_enum(converted_spec)
+    
+    # Convert anyOf nullable patterns
+    convert_anyof_nullable(converted_spec)
+    
+    return converted_spec