AMIGO Service

AMIGO Service

Version: 1.0.0
Status: 🚧 In Development
Start Date: 2025-10-14

Overview

AMIGO (AI-powered personal companion) is a standalone product that learns your unique communication style, remembers your context, and acts as your digital alter-ego. It helps individual professionals save time on routine communications and never miss important updates.

This is a SEPARATE product from Maestro. It can be deployed standalone or bundled with Maestro for enhanced value.

Product Vision

What AMIGO Does

• Daily Briefings: Summarizes your emails, PRs, tickets, meetings into a personalized brief
• Communication Drafts: Generates emails, Slack messages, Jira comments in YOUR tone
• Context Memory: Remembers project decisions, preferences, and historical context
• Proactive Notifications: Filters notifications to YOUR priorities
• Persona Learning: Adapts to your communication style over time (RLHF)

Target Users

• Individual professionals (developers, PMs, managers, executives)
• Anyone overwhelmed by notifications (50+ Slack messages, 30+ emails/day)
• Knowledge workers who value efficiency and work-life balance

Pricing

• AMIGO Starter: $20/user/month
• AMIGO Pro: $35/user/month (Email/Slack integrations)
• Bundle with Maestro: $50/user/month (includes both products)

Architecture

Tech Stack

• Language: Python 3.11+
• Framework: FastAPI
• Server: uvicorn
• Database: PostgreSQL 15+ with pgvector extension
• Cache: Redis 7+
• Queue: Redis Queue (RQ)
• Embeddings: OpenAI text-embedding-3-small (1536 dimensions)
• LLM: OpenAI GPT-4 or Anthropic Claude

Service Details

• Port: 3100
• API Prefix: /amigo/v1/
• Database: amigo_db
• Authentication: JWT (shared secret with Maestro for bundle deployments)

API Endpoints

/amigo/v1/health              GET   - Health check
/amigo/v1/auth/register       POST  - User registration
/amigo/v1/auth/login          POST  - User login
/amigo/v1/auth/refresh        POST  - Refresh JWT token
/amigo/v1/profile             GET   - Get user profile
/amigo/v1/profile             PUT   - Update profile
/amigo/v1/briefs/today        GET   - Get today's brief
/amigo/v1/drafts              GET   - List drafts
/amigo/v1/drafts              POST  - Create draft
/amigo/v1/drafts/:id          GET   - Get draft details
/amigo/v1/drafts/:id/approve  POST  - Approve draft
/amigo/v1/drafts/:id/send     POST  - Send draft (via Maestro HITL if bundle)
/amigo/v1/memory              GET   - Query memories
/amigo/v1/memory              POST  - Store memory
/amigo/v1/connectors          GET   - List integrations
/amigo/v1/connectors/:type    POST  - Connect integration (GitHub, Jira, Calendar)
/amigo/v1/feedback            POST  - Submit feedback (RLHF learning loop)

Project Structure

amigo-service/
├── src/
│   ├── api/                  # FastAPI routes
│   │   ├── __init__.py
│   │   ├── auth.py
│   │   ├── profile.py
│   │   ├── briefs.py
│   │   ├── drafts.py
│   │   ├── memory.py
│   │   ├── connectors.py
│   │   └── feedback.py
│   ├── services/             # Business logic
│   │   ├── __init__.py
│   │   ├── persona_service.py
│   │   ├── memory_service.py
│   │   ├── briefing_service.py
│   │   ├── drafting_service.py
│   │   ├── connector_service.py
│   │   └── feedback_service.py
│   ├── models/               # Pydantic models
│   │   ├── __init__.py
│   │   ├── user.py
│   │   ├── profile.py
│   │   ├── brief.py
│   │   ├── draft.py
│   │   ├── memory.py
│   │   └── connector.py
│   ├── database/             # SQLAlchemy models & migrations
│   │   ├── __init__.py
│   │   ├── models.py
│   │   └── session.py
│   ├── llm/                  # LLM integration
│   │   ├── __init__.py
│   │   ├── openai_client.py
│   │   └── anthropic_client.py
│   ├── utils/                # Utilities
│   │   ├── __init__.py
│   │   ├── auth.py           # JWT utils
│   │   ├── security.py       # Password hashing
│   │   └── dlp.py            # DLP/redaction
│   ├── config.py             # Configuration
│   └── main.py               # FastAPI app entry point
├── tests/
│   ├── __init__.py
│   ├── test_auth.py
│   ├── test_profile.py
│   ├── test_briefs.py
│   ├── test_drafts.py
│   ├── test_memory.py
│   └── conftest.py
├── alembic/                  # Database migrations
│   ├── versions/
│   ├── env.py
│   └── script.py.mako
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── scripts/
│   └── init_db.py            # Database initialization
├── .env.example
├── .gitignore
├── pyproject.toml            # Poetry dependencies
├── pytest.ini
└── README.md                 # This file

Development Setup

Prerequisites

• Python 3.11+
• PostgreSQL 15+ with pgvector extension
• Redis 7+
• Poetry (Python package manager)

Installation

1. Clone and setup:
``bash
cd amigo-service
python3 -m venv venv
source venv/bin/activate
pip install poetry
poetry install
``

2. Database setup:
```bash
# Create database
createdb amigo_db

# Enable pgvector extension
psql amigo_db -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Run migrations
alembic upgrade head
```

3. Environment configuration:
``bash
cp .env.example .env
# Edit .env with your settings
``

4. Run the service:
``bash
uvicorn src.main:app --host 0.0.0.0 --port 3100 --reload
``

5. Run tests:
``bash
pytest
``

Docker Setup (Alternative)

docker-compose up -d

Configuration

Environment Variables

# Server
PORT=3100
HOST=0.0.0.0
ENV=development  # development | staging | production

# Database
DATABASE_URL=postgresql://amigo_user:password@local-service/amigo_db

# Redis
REDIS_URL=redis://local-service/0

# JWT
JWT_SECRET=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRY_MINUTES=15
REFRESH_TOKEN_EXPIRY_DAYS=7

# LLM
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
LLM_PROVIDER=openai  # openai | anthropic

# Connectors
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
JIRA_CLIENT_ID=...
JIRA_CLIENT_SECRET=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# Optional: Maestro Integration (Bundle only)
MAESTRO_API_URL=local-service
MAESTRO_ENABLED=false

# Feature Flags
ENABLE_EMAIL_INTEGRATION=false
ENABLE_SLACK_INTEGRATION=false

Database Schema

Core Tables

• users - User accounts
• persona_profiles - User's communication style and preferences
• memories - Semantic memory storage (with pgvector embeddings)
• drafts - Communication drafts (emails, Slack, Jira)
• connectors - Integration configurations
• consent_registry - Per-integration consent tracking
• feedback - RLHF feedback from users
• audit_logs - All user actions

See src/database/models.py for complete schema.

API Documentation

Once running, visit:

• Swagger UI: local-service/docs
• ReDoc: local-service/redoc
• OpenAPI JSON: local-service/openapi.json

Development Roadmap

Week 1 (Current)

• [x] Project structure created
• [ ] FastAPI skeleton with basic endpoints
• [ ] Database schema and migrations
• [ ] JWT authentication
• [ ] Health check endpoint
• [ ] Docker configuration

Week 2-3

• [ ] PersonaService (persona profile CRUD)
• [ ] MemoryService (store/retrieve memories with embeddings)
• [ ] Basic API endpoints working with mock data

Week 4-5

• [ ] BriefingService (aggregate daily updates)
• [ ] DraftingService (generate communications in user's tone)
• [ ] Connector integrations (GitHub, Jira, Calendar OAuth)

Week 6

• [ ] FeedbackService (RLHF learning loop)
• [ ] Integration with Maestro's RAG (optional, for bundle)
• [ ] Alpha testing with 5 internal users

Week 7-10

• [ ] Frontend integration (AMIGO pages in maestro-frontend-production)
• [ ] Beta testing with 50 users
• [ ] Iteration based on feedback

Week 11-12

• [ ] Standalone deployment configurations
• [ ] Documentation complete
• [ ] Public launch preparation

Testing

Unit Tests

pytest tests/

Integration Tests

pytest tests/ -m integration

Coverage

pytest --cov=src tests/

Target Coverage

• Unit tests: ≥ 80%
• Integration tests: ≥ 70%
• Total coverage: ≥ 75%

Deployment

Deployment Modes

1. AMIGO-only (Standalone):
``bash
docker-compose -f docker-compose.amigo-only.yml up -d
``

2. Bundle (with Maestro):
``bash
docker-compose -f docker-compose.bundle.yml up -d
``

Production Checklist

• [ ] Environment variables configured
• [ ] Database migrations applied
• [ ] pgvector extension enabled
• [ ] Redis running
• [ ] SSL/TLS certificates configured
• [ ] Monitoring dashboards setup (Prometheus/Grafana)
• [ ] Log aggregation configured
• [ ] Backup strategy implemented

Monitoring & Observability

Health Checks

• Endpoint: GET /amigo/v1/health
• Expected Response:

``json
{
"status": "healthy",
"version": "1.0.0",
"timestamp": "2025-10-14T12:00:00Z",
"dependencies": {
"database": "healthy",
"redis": "healthy",
"llm": "healthy"
}
}
``

Metrics (Prometheus)

• amigo_requests_total - Total API requests
• amigo_request_duration_seconds - Request latency
• amigo_briefs_generated_total - Briefs generated
• amigo_drafts_created_total - Drafts created
• amigo_drafts_sent_total - Drafts sent
• amigo_memory_stored_total - Memories stored
• amigo_persona_accuracy - Persona tone accuracy score

SLOs

• Availability: 99.5% uptime
• API Latency (p95): < 200ms
• Brief Generation (p95): < 5s
• Draft Acceptance Rate: > 60%
• Persona Accuracy: > 80%

Security

Authentication

• JWT with short expiry (15 minutes)
• Refresh tokens (7 days)
• Token revocation via Redis blacklist

Data Protection

• Passwords hashed with bcrypt
• Embeddings encrypted at rest (pgcrypto)
• PII redaction in drafts (DLP pipeline)
• Multi-tenant RLS enforced at database level

Compliance

• GDPR: User data export and deletion endpoints
• SOC 2: Audit logging of all actions
• HIPAA: Encryption at rest and in transit

Contributing

Branch Strategy

• main - Production-ready code
• develop - Development branch
• feature/* - Feature branches
• hotfix/* - Production hotfixes

Commit Conventions

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• refactor: - Code refactoring
• test: - Adding tests
• chore: - Maintenance tasks

Pull Request Process

1. Create feature branch from develop
2. Implement feature with tests
3. Ensure all tests pass (pytest)
4. Submit PR with description
5. Get approval from 1+ reviewer
6. Merge to develop

Architecture Reference

For complete technical specification, see:

• AMIGO_SERVICE_ARCHITECTURE.md (maestro-frontend-production/AMIGO_SERVICE_ARCHITECTURE.md) - 1297 lines, complete architecture
• TWO_PRODUCTS_STRATEGY.md (maestro-frontend-production/TWO_PRODUCTS_STRATEGY.md) - 1912 lines, business strategy
• IMPLEMENTATION_SUMMARY_TWO_PRODUCTS.md (maestro-frontend-production/IMPLEMENTATION_SUMMARY_TWO_PRODUCTS.md) - Implementation summary

Support & Documentation

• Issues: https://github.com/your-org/amigo-service/issues
• Docs: https://docs.amigo.ai
• Status: https://status.amigo.ai
• Slack: #amigo-support

License

Proprietary - All Rights Reserved

Last Updated: 2025-10-14
Maintainer: Engineering Team
Status: 🚧 In Active Development