README.md

---

title: PENNY - Civic Engagement AI Assistant
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: latest
app_file: app.py
pinned: false
license: mit
---


# 🤖 PENNY - Civic Engagement AI Assistant

**Personal civic Engagement Nurturing Network sYstem**

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Azure ML](https://img.shields.io/badge/Azure-ML%20Ready-0078D4.svg)](https://azure.microsoft.com/en-us/services/machine-learning/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

---

## 📋 Overview

**PENNY** is a production-grade, AI-powered civic engagement assistant designed to help citizens connect with local government services, community events, and civic resources. Built with FastAPI and Hugging Face Transformers, Penny provides warm, helpful, and contextually-aware assistance for civic participation.

### ✨ Key Features

- **🏛️ Civic Information**: Local government services, voting info, public meetings
- **📅 Community Events**: Real-time local events discovery and recommendations
- **🌤️ Weather Integration**: Context-aware weather updates with outfit suggestions
- **🌍 Multi-language Support**: Translation services for inclusive access
- **🛡️ Safety & Bias Detection**: Built-in content moderation and bias analysis
- **🔒 Privacy-First**: PII sanitization and secure logging
- **⚡ High Performance**: Async architecture with intelligent caching

---

## 🏗️ Architecture
```

penny-v2/

├── app/                    # Core application logic

│   ├── main.py            # FastAPI entry point

│   ├── orchestrator.py    # Central coordination engine

│   ├── router.py          # API route definitions

│   ├── tool_agent.py      # Civic data & events agent

│   ├── weather_agent.py   # Weather & recommendations

│   ├── intents.py         # Intent classification

│   ├── model_loader.py    # ML model management

│   └── utils/             # Logging, location, safety utilities

├── models/                 # ML model services

│   ├── translation/       # Multi-language translation

│   ├── sentiment/         # Sentiment analysis

│   ├── bias/              # Bias detection

│   └── core/              # LLM response generation

├── data/                   # Static data & resources

│   ├── intents.json       # Intent classification data

│   └── civic_resources/   # Local government info

├── azure/                  # Azure ML deployment configs

└── requirements.txt        # Python dependencies

```

---

## 🚀 Quick Start

### Prerequisites

- Python 3.10 or higher
- Docker (optional, for containerized deployment)
- Azure subscription (for production deployment)

### Local Development Setup

1. **Clone the repository**
```bash

   git clone https://github.com/your-org/penny-v2.git

   cd penny-v2

```

2. **Create virtual environment**
```bash

   python -m venv venv

   source venv/bin/activate  # On Windows: venv\Scripts\activate

```

3. **Install dependencies**
```bash

   pip install --upgrade pip

   pip install -r requirements.txt

```

4. **Configure environment variables**
```bash

   # Create .env file with required variables:

   # AZURE_MAPS_KEY=your_azure_maps_key

   # ENVIRONMENT=development

   # DEBUG_MODE=false

```

5. **Run the application**
```bash

   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

```

6. **Access the API**
   - API: http://localhost:8000
   - Interactive docs: http://localhost:8000/docs
   - Health check: http://localhost:8000/health

---

## 🐳 Docker Deployment

### Build the container
```bash

docker build -t penny:latest .

```

### Run locally with Docker
```bash

docker run -p 8000:8000 \

  -e AZURE_OPENAI_KEY=your_key \

  -e WEATHER_API_KEY=your_key \

  penny:latest

```

---

## ☁️ Azure ML Deployment

### 1. Create Azure Resources
```bash

# Create resource group

az group create --name penny-rg --location eastus



# Create Azure ML workspace

az ml workspace create --name penny-workspace -g penny-rg



# Create Azure Container Registry

az acr create --name pennyregistry --resource-group penny-rg --sku Basic

```

### 2. Build and Push Container
```bash

# Login to Azure Container Registry

az acr login --name pennyregistry



# Build and tag image

docker build -t pennyregistry.azurecr.io/penny:v1 .



# Push to registry

docker push pennyregistry.azurecr.io/penny:v1

```

### 3. Deploy to Azure Container Instances
```bash

az container create \

  --resource-group penny-rg \

  --name penny-api \

  --image pennyregistry.azurecr.io/penny:v1 \

  --cpu 2 \

  --memory 4 \

  --registry-login-server pennyregistry.azurecr.io \

  --registry-username <username> \

  --registry-password <password> \

  --dns-name-label penny-civic-ai \

  --ports 8000 \

  --environment-variables \

    ENVIRONMENT=production \

    AZURE_OPENAI_KEY=<your-key>

```

---

## 🔧 Configuration

### Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `ENVIRONMENT` | Deployment environment (`development`, `production`) | No | `development` |
| `AZURE_MAPS_KEY` | Azure Maps API key (for weather) | Yes | - |
| `ENVIRONMENT` | Deployment environment | No | `development` |
| `DEBUG_MODE` | Enable debug endpoints | No | `false` |
| `ALLOWED_ORIGINS` | CORS allowed origins (comma-separated) | No | `*` |
| `LOG_LEVEL` | Logging level (`INFO`, `DEBUG`, `WARNING`) | No | `INFO` |
| `TENANT_ID` | Default tenant/city identifier | No | `default` |

### Azure Key Vault Integration (Recommended)

For production deployments, store secrets in Azure Key Vault:
```bash

# Create Key Vault

az keyvault create --name penny-keyvault --resource-group penny-rg



# Store secrets

az keyvault secret set --vault-name penny-keyvault --name openai-key --value "your-key"



# Reference in deployment

--environment-variables \

  AZURE_OPENAI_KEY="@Microsoft.KeyVault(SecretUri=https://penny-keyvault.vault.azure.net/secrets/openai-key/)"

```

---

## 📡 API Usage

### Send a message to Penny
```bash

curl -X POST "http://localhost:8000/chat" \

  -H "Content-Type: application/json" \

  -d '{

    "message": "What community events are happening this weekend?",

    "tenant_id": "norfolk",

    "user_id": "user123",

    "session_id": "session456"

  }'

```

### Response format
```json

{

  "response": "Hi! Here are some great community events happening this weekend in Norfolk...",

  "intent": "community_events",

  "tenant_id": "norfolk",

  "session_id": "session456",

  "timestamp": "2025-11-26T10:30:00Z",

  "response_time_ms": 245

}

```

---

## 🧪 Testing

### Run unit tests
```bash

pytest tests/ -v

```

### Run integration tests
```bash

pytest tests/integration/ -v

```

### Check code quality
```bash

# Linting

flake8 app/ models/



# Type checking

mypy app/ models/



# Format check

black --check app/ models/

```

---

## 📊 Monitoring & Logging

Penny uses structured JSON logging for production observability:

- **Application logs**: Stored in `/logs/` directory
- **Azure Application Insights**: Integration available for production
- **Health endpoint**: `/health` provides service status

### Log format
```json

{

  "timestamp": "2025-11-26T10:30:00Z",

  "level": "INFO",

  "intent": "weather_query",

  "tenant_id": "norfolk",

  "session_id": "abc123",

  "response_time_ms": 150,

  "success": true,

  "model_used": "gpt-4"

}

```

---

## 🛡️ Security & Privacy

- **PII Protection**: All logs sanitized before storage
- **Content Moderation**: Built-in bias and safety detection
- **Secrets Management**: Azure Key Vault integration
- **Non-root Container**: Security-hardened Docker image
- **HTTPS Only**: TLS/SSL required for production endpoints

---

## 🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Follow code style (Black, Flake8, MyPy)
4. Add tests for new features
5. Ensure all tests pass
6. Submit a pull request

### Code Standards

- **Type hints**: Required for all functions
- **Docstrings**: Google-style format
- **Error handling**: Structured try/except blocks
- **Logging**: Use `log_interaction()` for all operations
- **PII safety**: Always sanitize user data

---

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Built with [FastAPI](https://fastapi.tiangolo.com/)
- Powered by [Azure Machine Learning](https://azure.microsoft.com/en-us/services/machine-learning/)
- Civic data from local government open data initiatives

---

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/your-org/penny-v2/issues)
- **Documentation**: [Full docs](https://docs.penny-ai.org)
- **Email**: support@penny-ai.org

---

## 🗺️ Roadmap

- [ ] Multi-tenant dashboard
- [ ] Voice interface integration
- [ ] Advanced sentiment analysis
- [ ] Predictive civic engagement insights
- [ ] Mobile app integration

---

**Made with ❤️ for civic engagement**