| title | Aria |
|---|---|
| emoji | π€ |
| colorFrom | blue |
| colorTo | purple |
| sdk | gradio |
| sdk_version | 6.12.0 |
| app_file | app.py |
| pinned | false |
An intelligent, animated AI character with movement, gestures, and natural language interaction.
Live Demo Β· Aria Web UI Β· Quick Start
Aria is a full-stack interactive AI character platform. She lives on a virtual 3D stage, responds to natural language commands such as wave, pick up the ball, and dance, speaks via text-to-speech, and connects to multiple AI backends.
- Animated 3D character stage with object interaction
- Natural-language command parsing and action execution
- Multi-provider chat backends with local and cloud options
- Azure Functions API layer for chat, TTS, and AI services
- Experimental quantum ML, LoRA fine-tuning, and autonomous training workflows
- Lightweight Hugging Face Spaces deployment via Gradio
The project is organized around four core areas:
| Area | Folder | Description |
|---|---|---|
| Character interface | apps/aria/ |
Animated 3D character stage with object interaction |
| Chat / AI backends | ai-projects/chat-cli/ |
Multi-provider CLI and streaming chat API |
| Quantum ML | ai-projects/quantum-ml/ |
Hybrid quantum-classical training (experimental) |
| Model fine-tuning | AI/ |
LoRA fine-tuning for Aria's language understanding |
Supporting infrastructure lives in shared/, scripts/, config/, and function_app.py (Azure Functions API layer).
This repository is also configured to run as a Gradio Hugging Face Space.
- Spaces entry point:
app.py - Reusable demo helper:
scripts/gradio_hello.py - SDK:
gradio
The Spaces deployment exposes a lightweight AI chat app backed by the repository's existing provider abstraction. It can use the same provider layer as the rest of Aria (auto, local fallback, OpenAI-compatible providers, and more).
To run the Space locally:
./.venv/bin/python app.py
# or run the richer local Gradio UI
make start-gradioIf you want the full Aria platform instead, use the Quick Start steps below.
- Python 3.9+
- Git
- Azure Functions Core Tools for
func host start - Optional provider credentials for cloud-backed chat and speech features
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtcd apps/aria
pip install -r ../../requirements.txt
python server.py
# Open http://localhost:8080Type commands in the chat box: move left, wave, jump, pick up the ball, dance.
# Local mode β no API keys required
python ai-projects/chat-cli/src/chat_cli.py --provider local --once "Hello Aria!"
# OpenAI
OPENAI_API_KEY=sk-... python ai-projects/chat-cli/src/chat_cli.py --provider openai
# Azure OpenAI (requires all four env vars β see Configuration below)
python ai-projects/chat-cli/src/chat_cli.py --provider azureInteractive session commands: /new, /save, /exit.
func host start
# Endpoints: /api/chat, /api/chat-web, /api/tts, /api/quantum/*, /api/ai/status
curl http://localhost:7071/api/ai/status | python -m json.toolIf you only need the health endpoint, or func host start is unavailable, use the
lightweight local adapter instead:
make start-local-status
# or choose a different port when 7071 is already in use
make start-local-status FUNC_PORT=7072./.venv/bin/python app.py
# Local Gradio demo UI (chat/session tools)
make start-gradiomake build
make dev
# Aria: http://localhost:8080
# Functions: http://localhost:7071/api/ai/statusTo run the autonomous training orchestrator safely as a single instance:
python scripts/autonomous_training_orchestrator.py --cycles 1
# If a stale lock exists and you intentionally want takeover:
python scripts/autonomous_training_orchestrator.py --force-run --cycles 1make start-qai
# Open http://localhost:8000
# API docs: http://localhost:8000/docsIf your goal is to start building AI features quickly (providers, prompts, memory, or orchestration), use this path:
- Bootstrap env files
cp .env.example .env cp local.settings.json.example local.settings.json
- Install dependencies
python -m venv .venv source .venv/bin/activate pip install -r requirements.txt pip install -r requirements-dev.txt - Run a zero-key provider smoke check
python ai-projects/chat-cli/src/chat_cli.py --provider local --once "hello"
- Run the AI status endpoint locally (optional but recommended)
func host start curl http://localhost:7071/api/ai/status | python -m json.tool - Validate VS Code MCP wiring before agent/tool work
In VS Code you can also run the tasks
.venv/bin/python scripts/validate_mcp_setup.py # or structured output for automation .venv/bin/python scripts/validate_mcp_setup.py --jsonvalidate: mcp-setuporvalidate: mcp-setup-json. - Run fast validation before PRs
python scripts/test_runner.py --unit
For an AI-focused map of key modules and commands, see docs/guides/AI_CONTRIBUTOR_QUICKSTART.md.
apps/aria/ Animated character stage (HTML/CSS/JS + Python API server)
apps/chat/ Browser-based streaming chat UI
ai-projects/chat-cli/ Multi-provider chat CLI
ai-projects/quantum-ml/ Quantum ML platform (circuits, MCP server, Azure Quantum)
ai-projects/llm-maker/ Autonomous tool-creation system
ai-projects/cooking-ai/ Cooking-focused AI assistant
AI/ LoRA fine-tuning workspace (Phi / TinyLlama)
shared/ Shared Python modules (providers, DB, telemetry, Cosmos)
scripts/ Orchestration, training, evaluation, and utility scripts
config/ YAML configs for orchestrators
datasets/ Read-only training datasets
data_out/ All generated outputs (git-ignored)
function_app.py Azure Functions entry point (all /api/* endpoints)
Scope covered by integration baseline:
apps/aria/function_app.pyshared/ai-projects/*AI/scripts/orchestrators and integration tooling
Success criteria:
- One canonical local integration flow is runnable end-to-end.
- Integration contracts pass (
integration_smoke+ contract tests + orchestrator validation). /api/ai/statusand/api/ai/routeskeep expected provider and route contract shape.- Cross-surface API coverage remains present for chat, status, TTS, AGI stream, and quantum run routes.
- Canonical PR merge policy remains centered on
merge-gate.yml.
The Aria character stage runs at http://localhost:8080 or the GitHub Pages demo.
Natural language commands (examples):
| Command | Effect |
|---|---|
move left / move right |
Walk to stage edge |
wave / dance / jump |
Trigger gesture |
pick up the ball |
Pick up a nearby object |
throw the ball |
Throw held object with physics |
say hello |
Aria speaks the text aloud via TTS |
The auto-execute system parses complex multi-step requests such as walk to the table and pick up the apple into a structured sequence of 8 core actions: move, say, pickup, drop, throw, gesture, world, and expression.
Aria web server API (port 8080):
| Method | Path | Description |
|---|---|---|
GET |
/api/aria/state |
Current stage state (position, objects, expressions) |
POST |
/api/aria/command |
Process a natural language command |
POST |
/api/aria/execute |
Auto-execute an action sequence |
POST |
/api/aria/object |
Add / update / remove an object |
POST |
/api/aria/world |
Generate a themed world via LLM |
Provider auto-detection order:
LM Studio β Ollama β Azure OpenAI β OpenAI β Local (zero-dependency echo)
Pass --provider to override: local, openai, azure, lmstudio, ollama, lora, quantum, agi.
AZURE_OPENAI_API_KEY
AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_DEPLOYMENT
AZURE_OPENAI_API_VERSION
OPENAI_API_KEY
LoRA adapter β adapter directory must contain:
adapter_config.json
adapter_model.safetensors
python ai-projects/chat-cli/src/chat_cli.py --provider lora --model data_out/lora_training/lora_adapterAll providers implement BaseChatProvider.complete(messages, stream). Add a new provider by subclassing BaseChatProvider in shared/chat_providers.py.
Local Qiskit Aer simulation is free and unlimited. Azure simulator backends are also free. Real QPU hardware is billed per gate-shot, so always simulate first.
Workflow: Test locally β Validate on Azure simulator β Run on QPU (azure_confirm_cost: true in YAML required before hardware runs)
# Validate config without running anything
python scripts/quantum_autorun.py --dry-run
# Interactive training dashboard
cd ai-projects/quantum-ml && ./start_dashboard.sh
# Open http://localhost:5000
# Start the MCP server (8 quantum tools)
.venv/bin/python ai-projects/quantum-ml/quantum_mcp_server.pyMCP tools: create_quantum_circuit, simulate_quantum_circuit, get_quantum_circuit_properties, connect_azure_quantum, list_quantum_backends, submit_quantum_job, estimate_quantum_cost, get_job_status
Train a small model on Aria-specific datasets using LoRA adapters.
# Quick training run (TinyLlama, CPU-friendly, ~10β15 s)
python scripts/automated_training_pipeline.py --models tinyllama --quick
# Full train β evaluate β auto-promote best checkpoint
python scripts/train_and_promote.py --quick --auto-promote
# Validate configs without running
python scripts/autotrain.py --dry-runTraining datasets are in datasets/chat/aria_movement/, aria_expanded/, and aria_simple/ (read-only).
Outputs are written to data_out/lora_training/.
A background orchestrator continuously discovers datasets, trains, and evaluates models on a 30-minute cycle.
# Start the autonomous loop (runs indefinitely)
nohup python scripts/autonomous_training_orchestrator.py > data_out/autonomous_training.log 2>&1 &
# Check live status
cat data_out/autonomous_training_status.json | python -m json.tool
tail -f data_out/autonomous_training.logAn autonomous system where an LLM generates, validates, and sandboxes Python tools at runtime.
cd ai-projects/llm-maker
python examples/quick_start.py
.venv/bin/python llm_maker_mcp_server.pySecurity: no dangerous imports, no filesystem or network access, no eval / exec, sandboxed execution with resource limits.
# Canonical local integration baseline (contracts first, then smoke + targeted regression)
python scripts/ci_orchestrator.py --integration-baseline
# Fast unit tests (~0.5 s, no external services)
python scripts/test_runner.py --unit
# All fast tests (unit + integration, ~10 s)
python scripts/test_runner.py --all
# With coverage report
python scripts/test_runner.py --all --coverage
# Deterministic repository inspection agents (status freshness, markers, docstrings)
python scripts/run_repo_agents.py --dry-run
# One-command integration contract gate (local)
bash ./scripts/integration_contract_gate.sh
# Use the repo virtualenv explicitly when needed
PYTHON_BIN=.venv/bin/python bash ./scripts/integration_contract_gate.sh
# Strict gate (requires local Functions host at :7071)
bash ./scripts/integration_contract_gate.sh --strict-endpoints
# Focused provider + AGI regression check
python -m pytest ai-projects/chat-cli/src/test_chat_providers.py tests/test_agi_provider.py -q --tb=short
# Direct pytest
pytest -m "not slow and not azure" tests/VS Code users: open the Test Explorer for interactive test running and debugging.
https://bryan-roe.github.io/Aria
The demo runs in mock mode with simulated API responses, so no API keys are needed. For full AI capabilities, run the project locally.
Copy the example files to get started:
cp .env.example .env
cp local.settings.json.example local.settings.json
# Fill in API keys as neededNever commit secrets. Store keys in environment variables or local.settings.json for local development only.
Optional services (feature-flagged and safe to leave unset):
| Service | How to enable |
|---|---|
| SQL persistence | QAI_DB_CONN env var (SQLite, PostgreSQL, or Azure SQL) |
| Cosmos DB | QAI_ENABLE_COSMOS=true + COSMOS_ENDPOINT, COSMOS_KEY, COSMOS_DATABASE, COSMOS_CONTAINER |
| Application Insights | APPLICATIONINSIGHTS_CONNECTION_STRING |
| Azure Speech TTS | AZURE_SPEECH_KEY + AZURE_SPEECH_REGION |
| Local TTS fallback | QAI_ENABLE_LOCAL_TTS=true (uses pyttsx3 or gTTS when Azure credentials are absent) |
- If
func host startfails, install Azure Functions Core Tools and confirm it is on yourPATH, or usemake start-local-status. - If
http://localhost:8080orhttp://localhost:7071is unavailable, check for local port conflicts and trymake start-local-status FUNC_PORT=7072. - If cloud providers fail, verify the required environment variables are set correctly.
- If no provider credentials are configured, use
--provider localfor a zero-dependency fallback.
| Document | Purpose |
|---|---|
| apps/aria/README.md | Character stage API reference |
| ai-projects/quantum-ml/README.md | Quantum ML platform guide |
| ai-projects/chat-cli/README.md | Chat CLI reference |
| ai-projects/llm-maker/README.md | Tool maker guide |
| docs/aria/ | Aria movement and training documentation |
| docs/guides/AI_CONTRIBUTOR_QUICKSTART.md | AI-first onboarding path for contributors |
| MONETIZATION_GUIDE.md | Subscription and revenue system |
| docs/guides/REPO_AUTOMATION_GUIDE.md | Full repository automation reference |
| QUANTUM_LLM_TRAINING.md | Quantum-LLM concurrent training |
- Update
README.mdwhen adding configuration options, changing CLI flags, introducing new providers, or modifying cost behavior. - Put generated outputs under
data_out/(git-ignored). - Never modify files under
datasets/. - Run
--dry-runon orchestrators before executing GPU or QPU workloads. - Run tests before opening a pull request.
See individual project directories for license information.