Definable Backend Overview

Understanding the Definable AI platform architecture and capabilities

The Definable backend is a powerful, scalable system designed to provide AI-driven knowledge base and conversation capabilities. Built with modern asynchronous Python, the platform leverages FastAPI, PostgreSQL with vector extensions, and integrates with leading LLM providers.

Core Features

Knowledge Base Management

Store, index, and retrieve documents with semantic search capabilities

Conversational AI

Interact with LLMs through persistent conversation contexts

Multi-Organization Support

Isolated environments with role-based access control

Custom Agents

Configurable AI agents with specialized capabilities

Tool Integration

Extend agent capabilities with custom tools

LLM Provider Flexibility

Connect to various LLM providers (OpenAI, Anthropic, etc.)

System Architecture

Definable follows a modular, service-oriented architecture built with FastAPI:

Key Components

API Layer

The API layer provides RESTful endpoints for all platform functionality:

• FastAPI Framework: Modern, high-performance web framework
• Automatic Documentation: OpenAPI/Swagger docs for all endpoints
• Type Validation: Pydantic models for request/response validation
• Authentication: JWT-based auth with role-based access control

Service Layer

Services encapsulate business logic for specific domains:

• Authentication Service: User management, login, registration
• Knowledge Base Service: Document storage, indexing, and retrieval
• Organization Service: Multi-tenant organization management
• Conversation Service: LLM interaction and message history
• Agent Service: Configurable AI agent management
• Tool Service: Custom tool creation for agents

Data Layer

The data layer handles persistent storage and retrieval:

• PostgreSQL: Primary relational database
• pgvector Extension: Vector storage for embeddings
• SQLAlchemy ORM: Async database access with transaction support
• Alembic Migrations: Database schema version control

Integration Layer

The backend connects to various external services:

• LLM Providers: OpenAI, Anthropic, and others
• File Storage: S3-compatible storage for documents
• Email Services: User notifications and invitations

Key Features In Depth

Knowledge Base System

The knowledge base system allows storage and retrieval of documents with semantic search:

1. Document Upload

   Users upload documents in various formats (PDF, DOCX, TXT)

2. Text Extraction

   Text is extracted from documents using appropriate parsers

3. Chunking

   Documents are split into manageable chunks for embedding

4. Embedding Generation

   LLM-based embeddings are created for each chunk

5. Vector Storage

   Embeddings are stored in pgvector for efficient similarity search

6. Semantic Search

   User queries are converted to embeddings and matched against stored vectors

Conversation System

The conversation system enables persistent interactions with LLMs:

• Streaming Responses: Real-time streaming of LLM responses
• History Management: Persistent conversation history
• Context Window Management: Smart handling of token limits
• RAG Integration: Augment conversations with knowledge base results

Organization & RBAC

The multi-organization system with role-based access control:

• Organization Isolation: Data separation between organizations
• Role Hierarchy: Configurable role levels (Owner, Admin, Member, Guest)
• Fine-grained Permissions: Resource:action permission model
• Invitation Flow: Email-based user invitations

Technology Stack

• Language: Python 3.10+
• Web Framework: FastAPI
• Database: PostgreSQL 15+ with pgvector
• ORM: SQLAlchemy 2.0 (async)
• Authentication: JWT tokens
• Validation: Pydantic
• Testing: Pytest
• Linting: Ruff, mypy
• Deployment: Docker + Kubernetes

Getting Started

To get started with the Definable backend:

• Installation Guide: Setting up your development environment
• Environment Setup: Configuring required variables
• Development Workflow: Working with the codebase
• Architecture Details: In-depth architectural overview

API Reference

For API documentation, see the API Reference section.