Alfred AI is an event-driven, decoupled AI assistant platform built with Next.js 16, FastAPI, and Groq LLM (Llama 3.3 70B). Designed for speed, privacy, and modular extensibility.
In today's digital workflow, users face severe context fragmentation:
- App Switching Overhead: Constantly jumping between Gmail, Google Calendar, search engines, and note-taking apps destroys focus.
- Stateless Chatbots: Standard AI chatbots lack long-term memory of user preferences and cannot take actions on external services.
- Monolithic Bottlenecks: Traditional monolithic AI apps suffer from high response latencies, tight coupling, and lack of real-time streaming infrastructure.
Alfred AI resolves these issues by delivering a unified, autonomous digital assistant:
- ⚡ Sub-Second Streaming: Powered by Groq's hardware-accelerated Llama 3.3 70B engine via Server-Sent Events (SSE).
- 🧠 Persistent Server Memory: Remembers user context, preferences, and details across sessions.
- 🛠 Plug-and-Play Tools: Autonomous intent planning that executes tools for math, web search, email management, and calendar events.
- 🛡 Production Security: Strict domain isolation, JWT authentication, and Argon2id password hashing.
Alfred AI follows a strict Decoupled 3-Tier Architecture:
┌─────────────────────────────────────────────────────────┐
│ Frontend (Presentation Layer) │
│ React 19 / Next.js 16 (Turbopack) │
└────────────────────────────┬────────────────────────────┘
│ REST / SSE Stream
┌────────────────────────────▼────────────────────────────┐
│ Backend (API & Domain Layer) │
│ FastAPI Gateway • JWT Auth • Repositories • SQLite │
└────────────────────────────┬────────────────────────────┘
│ Event Bus / Direct Proxy
┌────────────────────────────▼────────────────────────────┐
│ AI Service (Reasoning Layer) │
│ AI Orchestrator • Intent Planner • Tool Registry │
└────────────────────────────┬────────────────────────────┘
│ OpenAI-Compatible API
┌────────────────────────────▼────────────────────────────┐
│ LLM Provider (Groq Cloud) │
│ Llama 3.3 70B Versatile Model │
└─────────────────────────────────────────────────────────┘
- User Request: User sends a prompt via the UI (e.g., "Summarize my recent unread emails").
- Intent Planning: The
LLMIntentPlanneranalyzes the input against registered tool schemas. - Tool Execution: If a tool is needed (e.g.,
email.get_unread_messages), theDefaultToolExecutorexecutes it and retrieves structured JSON data. - Context Assembly:
DefaultContextBuilderinjects memory, user profile data, and tool execution outputs into the system prompt. - Generation & SSE Streaming: Groq LLM generates the response, streamed word-by-word back to the user interface in real time.
Built using Domain-Driven Design (DDD) and clean layered architecture:
backend/app/
├── api/v1/ # Versioned REST controllers & SSE endpoints
├── core/ # Security (Argon2id, JWT), middleware, dependencies
├── database/ # SQLAlchemy models & async engine
├── events/ # RabbitMQ contracts & publisher
├── repositories/ # Abstract database access layer (User, Chat, Message, etc.)
└── services/ # Domain business logic (Auth, Chat, Message, Integration)
Alfred AI utilizes an Asynchronous Event-Driven Architecture:
- Domain Events:
user.created,message.received,message.stored,auth.login,auth.refreshed. - RabbitMQ Contract: Events are published to durable exchanges (
assistant.exchange). - Resilient Fallback: In offline local development, publishers catch connection exceptions gracefully to ensure zero downtime.
Extensible plug-and-play architecture (Tool base class + ToolRegistry):
| Tool | Registry Name | Description |
|---|---|---|
| 🧮 Calculator | calculator.compute |
Safe mathematical expression evaluation |
| 🔍 Web Search | search.web |
Real-time web search engine query |
| ✉️ Gmail Read | email.get_unread_messages |
Fetches & summarizes unread inbox emails |
| 📤 Gmail Send | gmail.send |
Composes & dispatches emails |
| 📅 Calendar | calendar.get_events |
Retrieves Google Calendar events |
POST /register— Register new user account & auto-create settings.POST /login— Authenticate and receive JWT access + refresh tokens.POST /refresh— Rotate access token using valid refresh token.GET /me— Retrieve current authenticated user profile.
GET /chats— List user conversations.POST /chats— Create a new conversation.POST /chats/{chat_id}/messages— Send user message.GET /chats/{chat_id}/messages/stream— SSE endpoint for real-time AI streaming.
- Working Memory: In-memory context window management for active conversation sessions.
- Semantic Memory: Server-side storage for user preferences and facts.
- Encrypted Storage: Sensitive data remains encrypted on the server side.
- Live Web App: http://localhost:3000
- Backend OpenAPI Docs: http://localhost:8000/docs
- AI Service OpenAPI Docs: http://localhost:8001/docs
- Python 3.9+
- Node.js 18+
git clone -b final2 https://github.com/Mohan14123/Albert.git Albert-final2
cd Albert-final2Create .env with your Groq API Key:
DEFAULT_AI_PROVIDER=openai
OPENAI_API_KEY=your_groq_api_key_here
OPENAI_API_BASE=https://api.groq.com/openai/v1
OPENAI_DEFAULT_MODEL=llama-3.3-70b-versatile
DATABASE_URL=sqlite+aiosqlite:///./assistant.dbpython3 -m venv venv
venv/bin/pip install eval_type_backport greenlet aiosqlite -r backend/requirements.txtPYTHONPATH=.:backend venv/bin/python3 -c "
import asyncio
from app.database.engine import engine
from app.database.base import Base
import app.database.models
async def init():
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
asyncio.run(init())
"Terminal 1 — AI Service (Port 8001):
PYTHONPATH=. venv/bin/uvicorn ai.main:app --host 0.0.0.0 --port 8001Terminal 2 — Backend API Gateway (Port 8000):
PYTHONPATH=backend venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000Terminal 3 — Frontend Web App (Port 3000):
cd frontend && npm install && npm run devdocker-compose up --build -dThis spins up PostgreSQL, Redis, RabbitMQ, FastAPI backend, AI Orchestrator, and Next.js frontend containers.
OpenAI Codex and AI pair-programming agents played a critical role in the architecting and development of Alfred AI:
- Phased Architecture Refactoring:
- Phase 4: Designed and implemented the repository pattern (
UserRepository,ChatRepository,MessageRepository,RefreshTokenRepository). - Phase 5: Developed the domain service layer (
AuthService,UserService,ChatService,MessageService) enforcing clean domain separation. - Phase 6: Built event contracts (
schemas.py,publisher.py) and graceful offline fallback mechanisms.
- Phase 4: Designed and implemented the repository pattern (
- Commit Granularity: Codex was utilized to automate atomic Conventional Commits for every newly created repository and service file.
- Cross-Version Python 3.9 Compatibility: Assisted in backporting type annotations (
from __future__ import annotations), dataclasses, and customStrEnumshims.
- Primary Model: Groq-accelerated
llama-3.3-70b-versatileserving as the core reasoning engine. - Prompt Engineering: Custom system instruction templates enforcing strict persona adherence ("You are Alfred, a helpful AI assistant").
- Robust Intent Planning: Multi-shot intent classification mapping user prompts directly to tool contracts.
- Multi-Agent Delegation: Subagent spawning for background web research and long-running analysis.
- Real-Time Voice Interface: Full duplex WebRTC voice streaming directly in the frontend UI.
- RAG Vector Search: Integration with pgvector & ChromaDB for deep document search across uploaded PDFs and documents.
- Full OAuth Integrations: One-click Google & Microsoft account linking for live email/calendar sync.
Licensed under the MIT License.