# AI Agent Production Deployment

Complete production-ready AI agent system with Langfuse observability, PostgreSQL persistence, and Docker deployment.

## Architecture

- **AI Agent API** (.NET 10) - Ports 6000 (gRPC), 6001 (HTTP)
- **PostgreSQL** - Database for conversations, revenue, and customer data
- **Ollama** - Local LLM (qwen2.5-coder:7b)
- **Langfuse** - Observability and tracing UI

## Quick Start

```bash
# 1. Deploy everything
./scripts/deploy.sh

# 2. Configure Langfuse (one-time setup)
#    - Open http://localhost:3000
#    - Create account and project
#    - Copy API keys from Settings → API Keys
#    - Update .env with your keys
#    - Restart API: docker compose restart api

# 3. Test the agent
curl -X POST http://localhost:6001/api/command/executeAgent \
  -H "Content-Type: application/json" \
  -d '{"prompt":"What is 5 + 3?"}'

# 4. View traces
#    Open http://localhost:3000/traces
```

## Features

✅ **Full Observability**: OpenTelemetry traces sent to Langfuse  
✅ **Database Persistence**: Conversations stored in PostgreSQL  
✅ **Function Calling**: Math and database query tools  
✅ **Health Checks**: `/health` and `/health/ready` endpoints  
✅ **Auto Migrations**: Database schema applied on startup  
✅ **Production Ready**: Docker Compose multi-container setup  

## Access Points

- HTTP API: http://localhost:6001/api/command/executeAgent
- Swagger: http://localhost:6001/swagger
- Langfuse: http://localhost:3000
- Ollama: http://localhost:11434

## Project Structure

```
├── docker-compose.yml          # Multi-container orchestration
├── Dockerfile                  # Multi-stage .NET build
├── .env                        # Configuration (secrets)
├── docker/configs/
│   └── init-db.sql            # PostgreSQL initialization
├── Svrnty.Sample/
│   ├── AI/
│   │   ├── OllamaClient.cs    # Instrumented LLM client
│   │   ├── Commands/
│   │   │   └── ExecuteAgent*  # Main handler (instrumented)
│   │   └── Tools/
│   │       ├── MathTool.cs    # Math operations
│   │       └── DatabaseQuery* # SQL queries
│   ├── Data/
│   │   ├── AgentDbContext.cs  # EF Core context
│   │   ├── Entities/          # Conversation, Revenue, Customer
│   │   └── Migrations/        # EF migrations
│   └── Program.cs             # Startup (OpenTelemetry, Health Checks)
└── scripts/
    └── deploy.sh              # One-command deployment
```

## OpenTelemetry Spans

The system creates nested spans for complete observability:

- `agent.execute` - Root span for entire agent execution
  - `tools.register` - Tool registration
  - `llm.completion` - Each LLM call
  - `function.{name}` - Each tool invocation

Tags include: conversation_id, prompt, model, success, latency, tokens

## Database Schema

**agent.conversations** - AI conversation history  
**agent.revenue** - Monthly revenue data (seeded)  
**agent.customers** - Customer data (seeded)  

## Troubleshooting

```bash
# Check service health
docker compose ps
curl http://localhost:6001/health

# View logs
docker compose logs api
docker compose logs ollama
docker compose logs langfuse

# Restart services
docker compose restart api

# Full reset
docker compose down -v
./scripts/deploy.sh
```

## Implementation Details

- **OpenTelemetry**: Exports traces to Langfuse via OTLP/HTTP
- **ActivitySource**: "Svrnty.AI.Agent" and "Svrnty.AI.Ollama"
- **Database**: Auto-migration on startup, seeded with sample data
- **Error Handling**: Graceful function call failures, structured logging
- **Performance**: Multi-stage Docker builds, health checks with retries

## Estimated Time: 3-4 hours for complete implementation