Skip to content

Bryan-Roe/Aria

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

1,591 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
title Aria
emoji πŸ€–
colorFrom blue
colorTo purple
sdk gradio
sdk_version 6.12.0
app_file app.py
pinned false

Aria β€” Interactive AI Character Platform

CI Pipeline Code Quality CodeQL E2E Tests Codespaces Prebuilds An intelligent, animated AI character with movement, gestures, and natural language interaction.

Live Demo Β· Aria Web UI Β· Quick Start


What is Aria?

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.

Features

  • 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).


πŸ€— Hugging Face Spaces

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-gradio

If you want the full Aria platform instead, use the Quick Start steps below.


πŸš€ Quick Start

Requirements

  • Python 3.9+
  • Git
  • Azure Functions Core Tools for func host start
  • Optional provider credentials for cloud-backed chat and speech features

Optional local setup

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

1 β€” Run the Aria web UI

cd apps/aria
pip install -r ../../requirements.txt
python server.py
# Open http://localhost:8080

Type commands in the chat box: move left, wave, jump, pick up the ball, dance.

2 β€” Chat via CLI (no UI required)

# 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 azure

Interactive session commands: /new, /save, /exit.

3 β€” Start the Azure Functions API host

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.tool

If 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

4 β€” Run the Hugging Face Space locally

./.venv/bin/python app.py
# Local Gradio demo UI (chat/session tools)
make start-gradio

5 β€” Local autonomous/dev stack with Docker Compose

make build
make dev
# Aria: http://localhost:8080
# Functions: http://localhost:7071/api/ai/status

To 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 1

6 β€” Start the QAI integration service

make start-qai
# Open http://localhost:8000
# API docs: http://localhost:8000/docs

🧭 AI Contributor Quickstart

If your goal is to start building AI features quickly (providers, prompts, memory, or orchestration), use this path:

  1. Bootstrap env files
    cp .env.example .env
    cp local.settings.json.example local.settings.json
  2. Install dependencies
    python -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt
    pip install -r requirements-dev.txt
  3. Run a zero-key provider smoke check
    python ai-projects/chat-cli/src/chat_cli.py --provider local --once "hello"
  4. Run the AI status endpoint locally (optional but recommended)
    func host start
    curl http://localhost:7071/api/ai/status | python -m json.tool
  5. Validate VS Code MCP wiring before agent/tool work
    .venv/bin/python scripts/validate_mcp_setup.py
    # or structured output for automation
    .venv/bin/python scripts/validate_mcp_setup.py --json
    In VS Code you can also run the tasks validate: mcp-setup or validate: mcp-setup-json.
  6. 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.


πŸ—οΈ Project Structure

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)

πŸ”— Entire-Repo Integration Scope & Success Criteria

Scope covered by integration baseline:

  • apps/aria/
  • function_app.py
  • shared/
  • 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/status and /api/ai/routes keep 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.

🎭 Aria Character

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

πŸ’¬ Chat Providers

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.

Environment variables

Azure OpenAI

AZURE_OPENAI_API_KEY
AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_DEPLOYMENT
AZURE_OPENAI_API_VERSION

OpenAI

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_adapter

All providers implement BaseChatProvider.complete(messages, stream). Add a new provider by subclassing BaseChatProvider in shared/chat_providers.py.


βš›οΈ Quantum ML (Experimental)

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.py

MCP 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


🧠 LoRA Fine-Tuning

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-run

Training datasets are in datasets/chat/aria_movement/, aria_expanded/, and aria_simple/ (read-only). Outputs are written to data_out/lora_training/.


πŸ€– Autonomous 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.log

πŸ”§ LLM Tool Maker

An 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.py

Security: no dangerous imports, no filesystem or network access, no eval / exec, sandboxed execution with resource limits.


πŸ§ͺ Testing

# 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.


🌐 Live Demo

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.


πŸ”’ Configuration & Secrets

Copy the example files to get started:

cp .env.example .env
cp local.settings.json.example local.settings.json
# Fill in API keys as needed

Never 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)

Troubleshooting

  • If func host start fails, install Azure Functions Core Tools and confirm it is on your PATH, or use make start-local-status.
  • If http://localhost:8080 or http://localhost:7071 is unavailable, check for local port conflicts and try make 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 local for a zero-dependency fallback.

πŸ“š Documentation

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

🀝 Contributing

  • Update README.md when 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-run on orchestrators before executing GPU or QPU workloads.
  • Run tests before opening a pull request.

πŸ“„ License

See individual project directories for license information.

About

Aria: An Automatic AI system designed to innovate and simplify tasks with intelligence. Explore cutting-edge artificial intelligence in Python.

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Sponsor this project

 

Contributors