# Foundry Local as API Sample

Dis sample dey show how pesin fit use Microsoft Foundry Local as REST API service without OpenAI SDK. E dey show direct HTTP integration pattern wey go give better control and customization.

## Overview

Based on Microsoft official Foundry Local pattern, dis sample dey provide:
- Direct REST API integration wit FoundryLocalManager
- Custom HTTP client implementation
- Model management and health monitoring
- Streaming and non-streaming response handling
- Production-ready error handling and retry logic

## Prerequisites

1. **Foundry Local Installation**
   ```powershell
   # Install from GitHub releases
   winget install Microsoft.FoundryLocal
   ```

2. **Python Dependencies**
   ```bash
   pip install foundry-local-sdk requests asyncio aiohttp
   ```

## Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Your App      │───▶│  REST API Client │───▶│  Foundry Local  │
│                 │    │                  │    │   Service       │
│ - Custom Logic  │    │ - HTTP Requests  │    │ - Model Loading │
│ - Business Rules│    │ - Authentication │    │ - Inference     │
│ - Data Pipeline │    │ - Error Handling │    │ - Health Check  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

## Key Features

### 1. **Direct HTTP Integration**
- Pure REST API calls without SDK dependency
- Custom authentication and headers
- Full control over request/response handling

### 2. **Model Management**
- Dynamic model loading and unloading
- Health monitoring and status check
- Performance metrics collection

### 3. **Production Patterns**
- Retry mechanism wit exponential backoff
- Circuit breaker for fault tolerance
- Comprehensive logging and monitoring

### 4. **Flexible Response Handling**
- Streaming responses for real-time application
- Batch processing for high-throughput scenarios
- Custom response parsing and validation

## Usage Examples

### Basic API Integration
```python
from api_client import FoundryAPIClient

# Initialize the API client
client = FoundryAPIClient()

# Simple completion
response = await client.complete(
    prompt="Explain quantum computing",
    model="phi-4-mini",
    max_tokens=500
)
print(response.content)
```

### Streaming Integration
```python
# Stream responses for real-time applications
async for chunk in client.stream_complete(
    prompt="Write a story about AI",
    model="phi-4-mini"
):
    print(chunk.content, end="", flush=True)
```

### Health Monitoring
```python
# Check service health
health = await client.health_check()
print(f"Service Status: {health.status}")
print(f"Active Models: {health.loaded_models}")
print(f"Memory Usage: {health.memory_usage}")
```

## File Structure

```
07/
├── README.md              # This documentation
├── requirements.txt       # Python dependencies
├── api_client.py         # Core API client implementation
├── health_monitor.py     # Health checking and monitoring
├── examples/
│   ├── basic_usage.py    # Simple API integration example
│   ├── streaming.py      # Streaming response example
│   ├── batch_processing.py # Batch processing example
│   └── production.py     # Production-ready implementation
└── tests/
    ├── test_api_client.py    # Unit tests for API client
    └── test_integration.py   # Integration tests
```

## Microsoft Foundry Local Integration

Dis sample dey follow Microsoft official pattern:

1. **SDK Integration**: E dey use `FoundryLocalManager` for service management
2. **REST Endpoints**: Direct calls to `/v1/chat/completions` and other endpoints
3. **Authentication**: Correct API key handling for local services
4. **Model Management**: Catalog listing, downloading, and loading pattern
5. **Error Handling**: Microsoft-recommended error codes and responses

## Getting Started

1. **Install Dependencies**
   ```bash
   pip install -r requirements.txt
   ```

2. **Run Basic Example**
   ```bash
   python examples/basic_usage.py
   ```

3. **Try Streaming**
   ```bash
   python examples/streaming.py
   ```

4. **Production Setup**
   ```bash
   python examples/production.py
   ```

## Configuration

Environment variables for customization:
- `FOUNDRY_MODEL`: Default model wey go dey use (default: "phi-4-mini")
- `FOUNDRY_TIMEOUT`: Request timeout in seconds (default: 30)
- `FOUNDRY_RETRIES`: Number of retry attempts (default: 3)
- `FOUNDRY_LOG_LEVEL`: Logging level (default: "INFO")

## Best Practices

1. **Connection Management**: Reuse HTTP connections for better performance
2. **Error Handling**: Implement correct retry logic wit exponential backoff
3. **Resource Monitoring**: Track model memory usage and performance
4. **Security**: Use correct authentication even for local services
5. **Testing**: Include both unit and integration tests

## Troubleshooting

### Common Issues

**Service No Dey Run**
```bash
# Check Foundry Local status
foundry status

# Start if needed
foundry start
```

**Model Loading Wahala**
```bash
# List available models
foundry model list

# Download specific model
foundry model download phi-4-mini
```

**Connection Errors**
- Check say Foundry Local dey run for correct port
- Confirm firewall settings
- Make sure say authentication headers dey correct

## Performance Optimization

1. **Connection Pooling**: Use session objects for multiple requests
2. **Async Operations**: Use asyncio for concurrent requests
3. **Caching**: Cache model responses where e dey necessary
4. **Monitoring**: Track response times and adjust timeouts

## Learning Outcomes

After you don complete dis sample, you go sabi:
- Direct REST API integration wit Foundry Local
- Custom HTTP client implementation pattern
- Production-ready error handling and monitoring
- Microsoft Foundry Local service architecture
- Performance optimization techniques for local AI services

## Next Steps

- Check Sample 08: Windows 11 Chat Application
- Try Sample 09: Multi-Agent Orchestration
- Learn Sample 10: Foundry Local as Tools Integration

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Disclaimer**:  
Dis dokyument don use AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator) take translate am. Even though we dey try make sure say e dey accurate, abeg make you sabi say translation wey machine do fit get mistake or no dey correct well. Di original dokyument for im native language na di one wey you go take as di correct source. For important information, e good make professional human translation dey use. We no go fit take blame for any misunderstanding or wrong interpretation wey fit happen because you use dis translation.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->