AI调酒师对话点单系统

MayaMCP

Originally created as a capstone project for Kaggle's Gen AI Intensive Course Q1 2025. Meant to demonstrate the skills in generative AI we've learned over the course of a week with a project of our own choosing that utilized at least 5 of those skills. Had 16 days to complete it.

After obtaining our Gen AI certificates from completing and submitting the first version of our service-working AI agent, we sought to complete it. Here in June, Gradio & Huggingface are holding an Agents & MCP hackathon, with multiple AI inference engine & foundation labs participating in the way of providing participants with free credits to build with throughout the duration of the competition.

So now this project has taken to the MCP turn. Where Anthropic's new protocol is taking the AI development by storm, creating yet another new paradigm is this ever-accelerating industry.

This second iteration of Maya, our AI agent, will be bolstered with the power of MCP, open-source AI frameworks, and hardware accelerators. Leaving behind the Google-based vendor lock-in it's initial iteration had with Gemini serving at it's base.

Features

• Multi-turn conversational ordering system
• Menu management with several beverages
• Real-time streaming voice chat
• Gradio UI with agent avatar
• Crypto Payment Integration (Coinbase CDP AgentKit on Base Sepolia)
  • $1000 starting balance for simulated bar experience
  • Live tab counter overlay on Maya's avatar
  • Animated balance/tab updates with visual feedback
  • Tip selection (10%, 15%, 20%) with toggle behavior
  • Crypto payments via Coinbase CDP AgentKit (with mock fallback)
  • Low balance warnings (orange < $50, red at $0)

Project Structure

• assets/: Static files (avatar, media)
• config/: Configuration files separate from code
• docs/: Additional documentation (ADRs, helper function reference docs/helper_functions.md)
• notebooks/: Experimentation and analysis
• scripts/: Utility scripts, including Google Cloud evaluation pipelines
• src/: Core source code with modular organization
  • src/eval/: Vertex AI Gen AI Evaluation Service (EvalTask), Antigravity Agent-as-a-Judge rubrics, zero-trust sanitization, and token efficiency scoring
  • src/routers/: FastAPI v1 REST and SSE API endpoints (session, payments, chat)
  • src/schemas/: Pydantic v2 data transfer schemas
  • src/utils/: Errors, helpers (centralized DRY logic cataloged in docs/helper_functions.md), and thread-safe state management
• tests/: pytest suite (unit, integration, property-based, API)
• .greptile/rules.md & .greptile/config.json: Greptile review agent rules and automated PR governance configuration

Architecture Updates

• Phaser 4 HTML5 Canvas Game Engine & Vite 8: Integrated interactive 2D retro canvas frontend (phaser@4.2.1) served at root /, with Vite 8 Rolldown bundling, a credential-gated exterior start screen, bottom-left bar soundtrack controls, and headless browser smoke testing (npm test).
• Cartesia 4.x Unified TTS SDK: Migrated voice synthesis to cartesia>=4.2.0,<5.0.0, using modern cartesia_client.tts.generate() binary response handling, non-blocking audio streaming, and sub-millisecond session cache key derivation.
• FastAPI 0.141.1 & Decoupled Architecture: Upgraded application server to FastAPI 0.141.1 (providing ~50% memory footprint reduction per container). Decoupled the Gradio frontend to /ui, mounting the Phaser 4 SPA at root / alongside native REST (/api/v1/*) and SSE interfaces.
• Python 3.11+ Baseline: Modernized project configuration (pyproject.toml, setup.py) to require Python >=3.11, enabling enum.StrEnum models and compatibility with scikit-learn>=1.9.1.
• Google ADK 2.0 Integration: Completely migrated the conversational orchestrator to Google's Agent Development Kit (ADK) using google-adk. Replaced legacy langchain and native google-genai wrappers with ADK's Agent, Runner, and Gemini models.
• Unified GenAI Client & 100% GCP Vertex AI Mode: Centralized provider authentication and session registry management using GCP Vertex AI mode (GCP_PROJECT, GCP_LOCATION, GEMINI_TIER=paid), removing Google AI Studio API key dependencies.
• Distributed State Management: Thread-safe per-session synchronization (RLock) supporting Modal's distributed modal.Dict sharing across multi-container deployments (max_containers > 1).

REST & SSE API Endpoints (/api/v1)

Maya exposes a REST and SSE API to allow building custom web and mobile client interfaces:

Note: For EventSource streaming, browser clients can pass session_id as a URL parameter (/api/v1/chat/stream?message=hello&session_id=sess_123). The stream yields an initial {"type": "session", "session_id": "sess_123"} event upon connection.

Model Information

• Default model: Google Gemini 3.5 Flash Lite (model id: gemini-3.5-flash-lite)
• You can override the model via GEMINI_MODEL_VERSION in your .env

Security

Maya features a built-in security layer that protects against:

• Prompt Injection & Toxicity: When the optional llm-guard dependency is installed, scans inputs for prompt injection and toxicity and outputs for toxicity. Without it, fallback regex checks cover only basic input-injection patterns; toxicity filtering and output scanning are unavailable.
• Application-Level Rate Limiting: Multi-level token-bucket protection against Denial-of-Wallet (DoW), automated request floods, and Cartesia TTS credit exhaustion. Defaults are calibrated for GCP Vertex AI Paid Tier throughput (MAYA_SESSION_RATE_LIMIT=60/min, MAYA_APP_RATE_LIMIT=500/min, MAYA_BURST_LIMIT=15/10s).

The security features fail open to ensure availability if scanning encounters unexpected errors.

To enable security features, ensure the optional dependencies are installed:

pip install ".[security]"
# or
pip install -r requirements.txt

Setup

Follow these steps to get Maya running locally.

Quick Start

1. Clone repository

git clone <repository-url>
cd MayaMCP

2. Create .env file with your GCP Vertex AI configuration:

# GCP Vertex AI Configuration (Exclusively uses GCP billing credits via Vertex AI)
# Required for Google Cloud Trace and Vertex AI Gen AI Evaluation Service (ADC)
GCP_PROJECT=your_gcp_project_id_here
GCP_LOCATION=global
GEMINI_TIER=paid

# Third-Party Service Keys (BYOK Fallback)
CARTESIA_API_KEY=your_cartesia_api_key_here

# Model Configuration (optional)
GEMINI_MODEL_VERSION=gemini-3.5-flash-lite
TEMPERATURE=1.0
MAX_OUTPUT_TOKENS=8192

# Rate Limiting & DoS Protection (optional — GCP Vertex AI Paid Tier defaults shown)
MAYA_SESSION_RATE_LIMIT=60      # requests per minute per session
MAYA_APP_RATE_LIMIT=500        # requests per minute globally
MAYA_BURST_LIMIT=15             # burst requests allowed in 10-second window

### Environment Configuration (optional)
PYTHON_ENV=development
DEBUG=True

3. Install and run Maya (recommended):

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
mayamcp

Alternative run:

python main.py

Legacy script (optional):

./run_maya.sh

Note: pip install -e . installs dependencies from requirements.txt and sets up the mayamcp console command.

Verifying Environment & High-Throughput Quota

# 1. Verify your environment setup (GCP Vertex AI Mode)
python verify_environment.py

# 2. Test high-throughput quota burst performance (20 parallel requests)
python burst_test.py 20

Note: pip install -r requirements.txt installs the Agent Development Kit (google-adk) and the native Google GenAI SDK (google-genai) used throughout src/. This project has been fully migrated to ADK 2.0 and does not use LangChain.

Credentials & Configuration

GCP Vertex AI (Google Cloud Platform)

1. Set up a GCP Project with billing enabled.
2. Ensure Vertex AI API is enabled.
3. Authenticate locally with Application Default Credentials:
   复制

   gcloud auth application-default login
   

4. Configure GCP_PROJECT and GCP_LOCATION in .env.
5. At the Phaser start screen, enter a GCP project ID accessible to those ADC credentials. Maya validates it before starting the session.

Cartesia TTS API (Optional Voice)

1. Visit Cartesia
2. Sign up for free tier
3. Generate API key
4. Add to .env as CARTESIA_API_KEY
5. Optionally enter the key on the Phaser start screen for session voice. Leave it blank to use text-only mode.

Cartesia Free Tier Limitations

The free Cartesia tier includes 20K credits per month, which provides approximately 15 minutes of conversation with Maya:

• Credits: 1 credit per character of text
• Typical usage: ~150 characters per Maya response = ~150 credits
• Monthly capacity: ~133 responses or ~15 minutes of audio
• Streaming impact: Improves responsiveness but doesn't extend duration

For extended usage, consider upgrading to a paid Cartesia plan.

Coinbase CDP (Simulated vs. Base Sepolia Testnet)

Maya's payment system operates in Optimistic UI Mode (zero latency tab clearing with background transaction processing). It supports two modes:

1. Simulation Mode (Default — No API Keys Required)

Works out of the box without any setup or API keys!

• If CDP_API_KEY_ID and CDP_API_KEY_SECRET are left blank in .env, Maya automatically runs in Simulation Mode.
• Payment transactions are processed instantly in sandbox mode with validly formatted 0x transaction hashes and clickable BaseScan Sepolia Explorer links for seamless local demos.

2. Base Sepolia Testnet Mode (Optional)

To connect Maya to real Base Sepolia testnet stablecoin (USDC) transactions:

1. Register for free at Coinbase Developer Platform (CDP)
2. Create an API key in the CDP Portal
3. Configure .env with your testnet environment variables:

# Required for real CDP testnet calls:
CDP_API_KEY_ID=your_cdp_key_id_here
CDP_API_KEY_SECRET=your_cdp_key_secret_here

# Optional: Persistent merchant wallet private key (auto-generates per session if empty)
CDP_MERCHANT_PRIVATE_KEY=0xYourPrivateKey

# Optional: Destination address for payments (defaults to built-in demo testnet wallet)
CDP_RECEIVER_ADDRESS=0xYourWalletAddress

⚠️ Important: Only use Base Sepolia testnet keys. Never use mainnet credentials — Maya is designed for simulated bar experiences.

Startup validation: On launch, Maya validates required API keys and logs clear, actionable messages if any are missing. The configured GEMINI_MODEL_VERSION is also checked against a known list; unrecognized models produce a warning without stopping the app.

Usage

This section covers typical usage patterns.

Running the Application

After setup, Maya will launch a Gradio web interface accessible at:

• Local: http://localhost:7860
• Public: Gradio will provide a shareable link

Interacting with Maya

Streaming Mode vs Traditional Mode

Maya now supports two interaction modes:

Streaming Mode (Default):

• Text appears in real-time as Maya generates responses
• Audio plays progressively as sentences are completed
• Reduced perceived latency from 3-8 seconds to near-instant feedback
• More conversational, responsive experience

Traditional Mode:

• Waits for complete response before displaying text
• Plays full audio response after text generation completes
• Original Maya behavior (fallback option)

Performance Improvements

The streaming implementation delivers significant user experience improvements:

Latency Reduction

• Before: 3-8 seconds total wait time (LLM + TTS)
• After: Text <1 second, audio starts 1-2 seconds
• Improvement: ~67-75% reduction in perceived response time

User Experience

• Real-time Feedback: See Maya's thoughts as they form
• Progressive Audio: Voice begins speaking while Maya continues generating
• Natural Conversation Flow: More like talking to a real bartender

Technical Features

• Sentence-by-Sentence TTS: Optimized for natural speech pacing
• Backward Compatibility: Traditional mode available as fallback
• Error Resilience: Graceful degradation if streaming fails
• Security Maintained: All input/output scanning preserved

Cartesia Free Tier Considerations

See the Cartesia Free Tier Limitations section above for details about streaming impact on free tier usage.

Ordering

• Example: "I'd like a martini on the rocks"

Checking order

• Example: "What's in my order?"

Recommendations

• Example: "Something fruity please"

Billing/Payment

• View bill: "What's my total?"
• Check balance: "What's my balance?"
• Add tip: Click tip buttons (10%, 15%, 20%) or say "Add a 20% tip"
• Pay: "I'll pay now"

Tab Counter & Balance Display

Maya's avatar includes a real-time tab overlay showing:

• Tab: Running total of your drink orders
• Balance: Remaining funds (starts at $1000)
• Tip buttons: Quick-select 10%, 15%, or 20% tip
• Visual feedback: Animated count-up effects when values change
• Low balance warnings: Orange text below $50, red at $0

The overlay updates automatically as you order drinks and is positioned at the bottom-left of Maya's avatar.

Voice Features

Maya speaks! Enable audio in your browser to hear her responses.

Testing

This project includes comprehensive tests for all major components. Tests are organized in the tests/ directory and use pytest for test discovery and execution.

Running Tests

Option 1: Using pytest directly (Recommended)

• Run tests: pytest
• Optional: coverage pytest --cov or verbose pytest -v

Option 2: Using pip install -e (Development mode)

• Install in editable mode: pip install -e .
• Run tests: pytest

Option 3: Frontend Browser Smoke Testing

• Build frontend: cd frontend && npm install && npm run build
• Run headless browser runtime test: npm test

Prerequisites: Python 3.11+ and Node.js 22.12.0+; activate your virtual environment if using one. Frontend browser smoke tests also require Chrome or Chromium installed at a recognized path, or CHROME_BIN set to its executable path.

Soundtrack assets

The start screen and bar player read frontend/public/assets/manifest.json. Place correctly encoded audio at the configured paths (or update the paths and titles), then set each ready entry's placeholder flag to false. soundtrack.startTrack selects the fixed start theme; soundtrack.playlist defines bar playback order. Placeholder or failed tracks are skipped, and the player disables its controls when no usable tracks remain.

Test Organization

• Unit Tests: Test individual functions and classes in isolation (using DummyLLM and ADK test doubles instead of legacy MagicMock).
• Integration Tests: Test component interactions and end-to-end workflows.
• Behavior-Driven Development (BDD): Test complex agentic interactions using Gherkin syntax via pytest-bdd (in tests/behavior/).
• Headless Evaluations: Automated dataset evaluations using Google Cloud Vertex AI Gen AI Evaluation Service (EvalTask) and Cloud Trace (scripts/run_evals.py / tests/eval/).
• Memvid Tests: Test RAG functionality and document retrieval.
• LLM Tests: Test ADK Agent integration and tool execution.
• UI Tests: Test user interface components and handlers.

Test Configuration

The project uses pytest.ini for test configuration with the following features:

• Automatic test discovery in the tests/ directory
• Custom markers for test categorization
• Strict configuration enforcement
• Colorized output for better readability
• Warning suppression for cleaner test output

Troubleshooting

Import Errors: If you encounter import errors, ensure you're using one of the recommended test methods above. The tests/conftest.py file automatically handles path setup for pytest runs.

Missing Dependencies: Install requirements and test tooling:

pip install -r requirements.txt
pip install pytest pytest-mock pytest-cov

CI/CD Integration

Tests are designed to run in CI environments with:

• No external API dependencies for unit tests
• Mocked third-party services for integration tests
• Configurable test execution based on available resources
• Proper exit codes for build pipeline integration

Evaluations (Vertex AI Gen AI Evaluation Service & Cloud Trace)

The project includes an evaluation pipeline using Google Cloud Vertex AI Gen AI Evaluation Service (vertexai.preview.evaluation / EvalTask) and Google Cloud Trace:

1. Authenticate with Google Cloud Application Default Credentials (ADC):
   复制

   gcloud auth application-default login
   

2. Configure GCP_PROJECT and GCP_LOCATION in .env.
3. Run evaluations using the provided script or agents-cli:
   复制

   # Vertex AI Gen AI Evaluation Pipeline (Pointwise, Trajectory, Viseme, & Agent-as-a-Judge)
   python scripts/run_evals.py
   
   # Deterministic Crypto Payment & Register Malfunction Recovery Evaluation
   python tests/eval/eval_crypto_payment.py
   

Tier-Based Concurrency:

• GCP Vertex AI Mode runs concurrently on Paid Tier (GEMINI_TIER=paid, 10+ QPS).
• If on Gemini Free Tier, evaluations run sequentially to respect the 15 RPM limit (GEMINI_TIER=free).

Cloud Trace & Telemetry:

• All evaluation runs generate OpenTelemetry spans conforming to GenAI Semantic Conventions (gen_ai.system, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens) exported directly to Google Cloud Trace.

Note on Mocking: When running standard pytest suites, always ensure the Native SDK and global RateLimiter are mocked properly (see tests/conftest.py for examples) to avoid accumulating state and hitting burst limits.

Troubleshooting

Import Errors: If you encounter import errors, ensure you're using one of the recommended test methods above. The tests/conftest.py file automatically handles path setup for pytest runs.

Missing Dependencies: Install requirements and test tooling:

pip install -r requirements.txt
pip install pytest pytest-mock pytest-cov

Example:

# optional: create and activate a clean virtual environment
python -m venv .venv && source .venv/bin/activate

# install project and test dependencies
pip install -r requirements.txt
pip install pytest pytest-mock pytest-cov

# run tests
pytest -q

API Key Issues: Most tests use mocked services, but some integration tests may require API keys. Check individual test files for specific requirements.

Error Handling and Graceful Fallbacks

• API call resilience: Specific handling for rate limits (429), authentication/authorization (401/403), and network timeouts; exponential backoff retries via tenacity; rich logging
• RAG fallbacks: Memvid -> FAISS -> no RAG, with warnings and safe empty results instead of crashes
• LLM and tool calling: Guards for missing/invalid responses, parameter validation for tool calls, and bartender-friendly fallback messages on failures
• TTS resilience: If Cartesia TTS fails, Maya responds with text-only; retry logic for transient errors
• User experience: Errors never break the conversational flow; logs include enough context for debugging without exposing sensitive information

Deployment

Agents-CLI & Docker

This project fully supports Google ADK agents-cli for streamlined deployment and testing. The repository includes an agents-cli-manifest.yaml and a Dockerfile for easy containerization.

• Start a new ADK workspace: agents-cli scaffold enhance .
• Build and run via Docker: docker build -t mayamcp . && docker run -p 7860:7860 mayamcp

Deployment on Modal

This project includes a Modal Labs deployment (see deploy.py). You can use the Modal CLI to develop and deploy:

• Development: modal serve deploy.py
• Deploy: modal deploy deploy.py

Resource configuration (environment variables)

The deployment function reads the following environment variables to configure resources without code changes:

• MODAL_MEMORY_MB (default: 4096)
  • Container memory in megabytes (e.g., 8192 for 8 GB)
• MODAL_MAX_CONTAINERS (default: 3)
  • Maximum number of containers for autoscaling/concurrency (e.g., 5)

You can set these environment variables in your deployment environment (e.g., Modal project/environment settings) to tune resource usage as you monitor real traffic.

Observability and tuning

At startup, the service logs the configured resource values and attempts to read cgroups for memory usage:

• Configured resources: MODAL_MEMORY_MB=..., MODAL_MAX_CONTAINERS=...
• Container memory usage at start: X.Y MB / Z.W MB

Use these to:

• Validate your configuration took effect
• Monitor headroom vs. actual usage
• Iterate on MODAL_MEMORY_MB and MODAL_MAX_CONTAINERS based on load and p95 latency

Required Vertex AI configuration (GCP_PROJECT, GCP_LOCATION, GEMINI_TIER=paid) is expected via environment variables/secrets as before. CARTESIA_API_KEY is optional; omit it to run Maya in text-only mode.

Deployment checklist

Use this quick checklist when deploying on Modal:

• Vertex AI configuration
  • GCP_PROJECT
  • GCP_LOCATION
  • GEMINI_TIER=paid
• Voice configuration (optional)
  • CARTESIA_API_KEY — omit for text-only mode
• Resource tuning (optional)
  • MODAL_MEMORY_MB (e.g., 4096, 8192)
  • MODAL_MAX_CONTAINERS (e.g., 3, 5)
• Expected startup logs
  • Configured resources: MODAL_MEMORY_MB=..., MODAL_MAX_CONTAINERS=...
  • Container memory usage at start: ...