Local-first autonomous AI runtime — persistent memory, a tool-permission engine, and LangGraph orchestration, running headless on your own machine.

Quick Start · Features · Architecture · Documentation · Security

---

Amadeus is a secure autonomous AI operating layer — a persistent cognitive runtime, not just a chatbot. It runs as a headless daemon that plans, acts, verifies, and remembers, built on Clean Architecture with an explicit LangGraph execution graph you can pause, audit, and resume.

It's designed to be local-first: inference can run entirely on your own hardware (local GGUF models), and LOCAL_ONLY_MODE=true disables every cloud provider so nothing leaves the machine.

Why Amadeus?

Most agent stacks	Amadeus
Brittle ReAct loops that lose state	Deterministic LangGraph state machine — every task is an auditable, resumable execution graph
Tools bolted into core code	Hot-pluggable tools — drop a .py file into plugins/, loaded on next restart
No security layer on tool calls	Tool Policy Engine — risk levels + graduated permission profiles that fail closed
"Local" sandboxes that are trivially escapable	Hardened Docker sandbox, disabled by default, refuses to run untrusted code when unavailable
Cloud-only inference	Local-first fallback chain: local GGUF → Groq → Gemini
Amnesia between sessions	Persistent episodic + semantic memory in PostgreSQL + a local vector store

Quick Start

Requirements: Python 3.11+, uv, and at least one LLM API key (Groq is free).

git clone https://github.com/adityatawde9699/Amadeus-AI.git
cd Amadeus-AI
uv sync --all-extras --dev

cp .env.example .env          # set SECRET_KEY and GROQ_API_KEY (minimum)
uv run alembic upgrade head   # initialise the database

Then start whichever interface fits your use case:

# API host — REST + admin surface, interactive docs at http://localhost:8000/docs
uv run python -m src.transports.fastapi_transport

# Telegram-first local daemon (needs TELEGRAM_BOT_TOKEN + MASTER_TELEGRAM_CHAT_ID)
uv run amadeus-daemon

Prefer containers? docker-compose up --build -d brings up the API, worker, Postgres, Redis, and Qdrant. Full walkthrough → Quick Start wiki.

Minimum viable setup: Python 3.11 + ~1 GB RAM + a free GROQ_API_KEY. Redis and the vector store are optional — the daemon degrades gracefully without them.

Features

• Autonomous agent lifecycle — plan-driven reasoning, self-reflection on tool failures, and durable state that survives restarts.
• 70+ sandboxed tools — system control, networking, filesystem, productivity, and research, each mapped to a risk level.
• Fail-closed security — graduated permission profiles, prompt-injection resistance, SSRF egress protection, and pre-auth rate limiting.
• Local-first inference — priority-ordered LLM routing with Redis-backed daily quota tracking; LOCAL_ONLY_MODE for 100% privacy.
• Persistent memory — every plan, step, and reflection is stored in PostgreSQL for a full behavioral audit; semantic recall via a local vector store.
• Omni-Workspace RAG — hybrid BM25 + dense retrieval so the agent can search your codebase and local files.
• Multi-transport — one AmadeusService behind FastAPI (REST), Telegram, and a CLI.

LLM routing:  LlamaCpp (local GGUF)  →  Groq (Llama 3.3 70B)  →  Gemini 3 Flash

Architecture

Amadeus follows Clean Architecture — dependencies point inward, and the core layer has zero external dependencies.

Clients — HTTP · Telegram · CLI
    ↓
Transport — src/transports/
    ↓
Application — AmadeusService · LangGraph · ToolDispatcher
   ↙            ↓
Core — domain models · interfaces · settings
   ↘
Infrastructure — LLM adapters · DB · cache · memory · tools
    ↓
Data — PostgreSQL · Redis · Vector store

Deep dives — Architecture · Core Systems · LLM Routing & Quota.

Documentation

The full documentation lives in the project wiki:

Page	What's inside
Quick Start	Prerequisites, local install, Docker, offline mode
Configuration Reference	Every .env variable explained
Architecture	Layer diagram, request lifecycle, memory tiers
Tool Registry	All 70+ tools by category
API Reference	Chat, messaging, tasks, health endpoints
Security Model	Auth, sandboxing, tool execution safety
Deployment	Docker Compose, systemd, Railway, Windows service
Development Guide	Adding tools & LLM providers, testing, coding standards
Known Limitations & Roadmap	Current gaps and what's next

Tech Stack

Python 3.11+ · FastAPI · SQLAlchemy 2.0 · PostgreSQL · Redis · LangGraph · Groq (Llama 3.3) · Gemini · llama-cpp-python · ONNX Runtime · Turbovec · Docker

Security

Amadeus is built to fail closed — when a security-relevant precondition is missing, it denies rather than allows. Highlights: graduated tool permissions, a Docker-only code sandbox (disabled by default), SSRF egress protection, a Telegram allowlist that rejects all senders when unset, and pre-auth rate limiting.

Found a vulnerability? Please follow the Security Policy — do not open a public issue.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md and the Development Guide, and please observe the Code of Conduct. Good first issues are labelled in the issue tracker.

License

Apache License 2.0 — see LICENSE.txt. Copyright © 2024 Aditya Tawde.

Aditya Tawde · Report a bug · Changelog