Onagi

The Vision

Onagi is a play on AGI—designed to be a weightless, frictionless nexus between your business data and generative intelligence. Unlike standard wrappers, Onagi is built on a distributed microservices architecture to handle millions of tokens and concurrent users with sub-second TTFT (Time To First Token).

Key Engineering Features

• 🚀 Antigravity UX: Zero-latency streaming via Server-Sent Events (SSE).
• 🧠 Smart Retrieval: Semantic search using pgvector with strict metadata filtering.
• 🛡️ Strict Multi-Tenancy: Logic-level and DB-level (RLS ready) data isolation.
• 🕸️ Playwright Ingestion: Headless browser-based scraping for modern SPA/Javascript websites.
• ⚡ Semantic Caching: Redis-powered caching to reduce LLM costs and latency by 90%.
• 📦 Framework-Agnostic: Shadow-DOM Web Component widget embeddable on any site.

The Tech Stack

• Backend: FastAPI (Python 3.12+), SQLAlchemy 2.0, Asyncpg.
• AI Engine: Gemini Flash Latest.
• Task Queue: Celery + Redis.
• Database: PostgreSQL 16 + pgvector.
• Frontend: Next.js 16 (Dashboard), Vanilla JS (Widget).
• Infrastructure: Docker, Terraform.

Project Structure

• app: FastAPI backend handling API requests, business logic, and database interactions.
• dashboard: Next.js frontend for managing knowledge bases and viewing analytics.
• widget: Embeddable chat widget (Vanilla JS/Lit) for integration into external sites.
• docker: Docker configurations and Dockerfiles.

Architecture Diagram

graph TD
    User-->|Widget|API[FastAPI Gateway]
    API-->|Vector Search|DB[(PostgreSQL + pgvector)]
    API-->|History|Cache[(Redis)]
    API-->|Stream|Gemini[Gemini Flash Latest]
    Worker[Celery Worker]-->|Scrape|Playwright[Headless Chrome]
    Worker-->|Embed|Gemini

Loading

Getting Started

Prerequisites

• Docker & Docker Compose
• Python 3.12+ (for local backend dev)
• Node.js (for local frontend dev)

Setup & Run (Docker)

1. Clone the repository:

   git clone <repository-url>
   cd onagi

2. Environment Configuration: Copy the example environment file:

   cp .env.example .env

   Update .env with your API keys (e.g., GEMINI_API_KEY).

3. Start with Docker Compose:

   docker-compose up --build

   This will start the API, Worker, Database, Redis, and likely the Dashboard if configured.

Local Development

Backend (FastAPI)

1. Navigate to the root directory.
2. Install dependencies using Poetry:

   poetry install

3. Run the development server:

   poetry run uvicorn app.main:app --reload

Frontend (Dashboard)

1. Navigate to the dashboard directory:

   cd dashboard

2. Install dependencies:

   npm install

3. Run the development server:

   npm run dev

Widget

The widget is located in the widget/ directory. It is designed to be a standalone script (onagi-chat.js) and stylesheet (styles.css) that can be embedded into any HTML page.

Testing

Run backend tests to ensure stability:

poetry run pytest