Merge pull request #35 from ks6088ts-labs/copilot/fix-34

Enhance documentation, testing, and logging functionality

Author: ks6088ts

.env.template

@@ -31,3 +31,6 @@ MICROSOFT_GRAPH_TENANT_ID="<YOUR_TENANT_ID>"
 MICROSOFT_GRAPH_CLIENT_ID="<YOUR_CLIENT_ID>"
 MICROSOFT_GRAPH_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
 MICROSOFT_GRAPH_USER_SCOPES="User.Read Sites.Read.All" # scopes for Microsoft Graph API
+
+# Logging Configuration
+LOG_LEVEL="INFO" # Valid levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

README.md

@@ -6,54 +6,182 @@
 
 # template-fastapi
 
-This is a template repository for Python
+A comprehensive FastAPI template with Azure cloud services integration, Agent-based workflows, and multi-service API architecture.
 
-## Prerequisites
+## Features
+
+- **Multiple API Services**: Items management, file operations, restaurant discovery, speech transcription, and agent-based chat
+- **Azure Cloud Integration**: CosmosDB, Blob Storage, OpenAI, AI Speech, and Application Insights
+- **Agent Workflows**: LangGraph and Azure AI Foundry integration for conversational AI
+- **Real-time Communication**: WebSocket-based chat functionality
+- **Comprehensive Logging**: Configurable log levels with structured error handling
+- **Testing & Quality**: 37+ automated tests with logging and monitoring
+- **Container Ready**: Docker support with multi-stage builds
+
+## Quick Start
+
+### Prerequisites
 
 - [Python 3.10+](https://www.python.org/downloads/)
-- [uv](https://docs.astral.sh/uv/getting-started/installation/)
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or pip
 - [GNU Make](https://www.gnu.org/software/make/)
 
-## Development instructions
+### Installation
 
-### Local development
+```bash
+# Clone the repository
+git clone https://github.com/ks6088ts-labs/template-fastapi.git
+cd template-fastapi
 
-Use Makefile to run the project locally.
+# Install dependencies
+make install-deps-dev
 
-```shell
-# help
-make
+# Copy environment template
+cp .env.template .env
+# Edit .env with your Azure service credentials
+```
 
-# install dependencies for development
-make install-deps-dev
+### Running the Application
 
-# run tests
+```bash
+# Development server with hot reload
+make dev
+
+# Production server
+make run
+
+# Run tests
 make test
 
-# run CI tests
-make ci-test
+# View documentation
+make docs-serve
+```
+
+The API will be available at http://localhost:8000 with interactive documentation at http://localhost:8000/docs.
+
+## API Services
+
+### Core Services
+
+- **Items API** (`/items/`): CRUD operations for item management
+- **Files API** (`/files/`): File upload, download, and management with Azure Blob Storage
+- **Restaurants API** (`/foodies/`): Restaurant discovery with geospatial search
+- **Speech API** (`/speeches/`): Batch transcription jobs using Azure AI Speech
+
+### Agent Services
+
+- **LangGraph Agents** (`/agents/langgraph/`): AI agents with custom tools
+- **Azure AI Foundry** (`/agents/azure-ai-foundry/`): Thread-based conversations
+- **Chat Interface** (`/chats/`): Real-time WebSocket chat with agent integration
+
+### Demo & Utilities
+
+- **Demo Endpoints** (`/demos/`): Dice rolling, flaky endpoints for testing
+- **Health & Monitoring**: Application Insights integration with OpenTelemetry
+
+## Configuration
+
+### Environment Variables
+
+Key configuration options in `.env`:
+
+```bash
+# Logging
+LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+# Azure OpenAI
+AZURE_OPENAI_ENDPOINT=https://<name>.openai.azure.com/
+AZURE_OPENAI_API_KEY=<key>
+AZURE_OPENAI_MODEL_CHAT=gpt-4o
+
+# Azure Storage & Database
+AZURE_COSMOSDB_CONNECTION_STRING=<connection-string>
+AZURE_BLOB_STORAGE_CONNECTION_STRING=<connection-string>
+
+# Monitoring
+APPLICATIONINSIGHTS_CONNECTION_STRING=<connection-string>
 ```
 
-### Docker development
+See `.env.template` for complete configuration options.
+
+## Docker Deployment
 
-```shell
-# build docker image
+```bash
+# Build image
 make docker-build
 
-# run docker container
-make docker-run
+# Run container
+docker run -p 8000:8000 --env-file .env ks6088ts/template-fastapi:latest
+```
+
+## Development
+
+### Project Structure
+
+```
+template_fastapi/
+├── routers/          # API route handlers
+│   ├── agents/       # Agent-based endpoints
+│   ├── chats.py      # WebSocket chat
+│   ├── demos.py      # Demo endpoints
+│   ├── files.py      # File operations
+│   ├── foodies.py    # Restaurant API
+│   ├── items.py      # Items CRUD
+│   └── speeches.py   # Speech transcription
+├── models/           # Pydantic data models
+├── repositories/     # Data access layer
+├── settings/         # Configuration management
+└── templates/        # Jinja2 templates
+```
+
+### Testing
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage
+pytest --cov=template_fastapi
 
-# run CI tests in docker container
-make ci-test-docker
+# Run specific test file
+pytest tests/test_api.py -v
 ```
 
-## Deployment instructions
+### Code Quality
 
-### Docker Hub
+```bash
+# Format code
+make format
 
-To publish the docker image to Docker Hub, you need to [create access token](https://app.docker.com/settings/personal-access-tokens/create) and set the following secrets in the repository settings.
+# Lint code
+make lint
 
-```shell
-gh secret set DOCKERHUB_USERNAME --body $DOCKERHUB_USERNAME
-gh secret set DOCKERHUB_TOKEN --body $DOCKERHUB_TOKEN
+# Apply auto-fixes
+make fix
 ```
+
+## Azure Functions Deployment
+
+The application supports Azure Functions deployment:
+
+```bash
+# Export requirements
+uv export --format requirements-txt --no-dev --no-hashes --output-file requirements.txt
+
+# Deploy to Azure Functions
+func azure functionapp publish <function-app-name>
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes with tests
+4. Run quality checks (`make ci-test`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.