AllaTre AI Backend

The AllaTre AI Backend is a high-performance, auxiliary satellite service engineered to drive intelligent discovery, personalized recommendations, and policy-grounded support for the AllaTre C2C auction platform in Egypt and the MENA region.

Built with FastAPI, this system bridges the gap between traditional relational database engines and modern AI architectures. It operates alongside the primary backend microservices, ingesting auction data from the source PostgreSQL database and synchronizing high-speed search and vector indices via event-driven webhook streams.

---

System Architecture

The AI Backend leverages a hybrid data indexing model, combining traditional inverted-index keyword searches with semantic vector spaces.

graph TD
    C[Client / Frontend App] -->|Interactive Queries| F[FastAPI AI Backend]
    
    subgraph FastAPI Lifespan Startup & Warmup
        F -->|1. Pre-warms Connection Pool| DB[(PostgreSQL DB)]
        F -->|2. Syncs Base Synonyms| MS[(Meilisearch Host)]
        F -->|3. Local Warmup Query| ST[Sentence-Transformers Model]
    end

    subgraph Service Engines & Pipelines
        F -->|7-Step Search Pipeline| SE[Discovery Engine]
        F -->|Dual-Strategy & Affinity| RE[Recommendation Engine]
        F -->|Grounded RAG Assistant| CE[Legal Chatbot]
    end

    subgraph Hybrid Indexing & Storage
        SE -->|BM25 Matches| MS
        SE -->|pgvector Similarity| DB
        RE -->|Read-Through Caching| RD[(Redis Cache)]
        CE -->|Policy Embeddings| DB
    end

    style F fill:#005571,stroke:#fff,stroke-width:2px,color:#fff
    style MS fill:#FF5145,stroke:#fff,stroke-width:2px,color:#fff
    style RD fill:#DC382D,stroke:#fff,stroke-width:2px,color:#fff

Loading

---

Core Technical Concepts & Feature Modules

1. Intelligent Discovery Engine (7-Step Search Pipeline)

The search backend employs a robust, multi-phase retrieval pipeline to ensure relevant results even with complex, natural language, or misspelled queries:

• Step 0: Parallel AI Query Parsing & Embedding Warmup When a natural language query is received, the system runs an AI Query Parser (QueryParserService) that extracts structural filter fields (e.g., product keywords, price bounds, category names, cities) in parallel with CPU-based text normalization.
  • Dual Provider Fallback: The parser tries a high-speed primary LLM provider (Groq) first. If Groq is unavailable, it automatically falls back to a secondary provider (Hugging Face Inference API) without dropping the request.
  • Confidence Guardrails: Extracted filters are only applied if the model's confidence exceeds a configurable threshold.
• Step 1: Normalization: The raw query is normalized into clean tokens.
• Step 2: Prefix Matching: Meilisearch is used to perform fast matching on prefix strings.
• Step 3: Typo Correction & "Did You Mean?": Matches are validated against the active database. If the result count falls below a threshold, a did-you-mean spelling correction is triggered.
• Step 4: Base Synonym Expansion: The query is enriched with synonyms loaded dynamically from synonyms_base.json.
• Step 5: Lexical Search: BM25 keyword retrieval is performed via Meilisearch.
• Step 6: Semantic Vector Search: Semantic similarity is evaluated against high-dimensional embeddings stored in pgvector using local SentenceTransformer models.
  • Reciprocal Rank Fusion (RRF): The system fuses results from both the lexical and semantic search legs using a customizable RRF algorithm, balancing relevance across keyword matches and semantic intents.
• Step 7: Zero-Results Fallback: If no direct matches are found, the pipeline gracefully falls back to surfacing localized trending auctions and popular category listings, avoiding dead ends for the user.

2. Context-Aware Recommendation Engine

The recommendation framework operates entirely on GET-based read actions to optimize for client-side rendering and web-standard caching:

• Dual-Strategy Recommendation:
  • Returning Users (Behavioral Strategy): Maps recent user interactions (views, bids, watchlist additions) to active auctions using pgvector similarity.
  • Cold Start (Heuristic Strategy): Surfaces trending auctions, new listings, and high-engagement items to build initial interest profiles.
• Multiplicative Category Affinity: Leverages a mathematical user-interest matrix. If a user repeatedly interacts with specific auction categories, those categories receive a 1.4x multiplicative boost in their affinity scores, dynamically bubbling relevant auctions to the top of their feed.
• Cross-Section Deduplication: Enforces strict item deduplication across trending, ending-soon, and customized feed sections to maximize user engagement.
• Read-Through Cache: Integrates a Redis caching layer to store feed response objects. Requests hitting the feed are resolved in milliseconds, with cache objects expiring automatically according to a configurable Time-To-Live (TTL).

3. Grounded Legal RAG Assistant

A Retrieval-Augmented Generation (RAG) assistant is built directly into the service to answer platform-specific legal and operational questions (e.g., terms of service, bidding rules, privacy policies):

• Zero-Hallucination Guardrails: Queries are answered only if matching source text can be retrieved from database-indexed legal chunks. If no relevant source context meets the semantic similarity threshold, the assistant falls back to a clean, custom message (e.g., "couldn't find information") rather than hallucinating details.
• Dynamic Document Chunking: Supports configurable sliding-window text chunking (RAG_CHUNK_SIZE and RAG_CHUNK_OVERLAP) to keep context limits optimized for LLM completion requests.

4. Real-Time Webhook Synchronization

To maintain index consistency without database polling, the service integrates high-speed webhooks:

• Auction Sync: Listens to create, update, and delete events. Creating or updating an auction triggers synchronous indexing in Meilisearch and asynchronous generation of vector embeddings for pgvector storage.
• Legal Document Sync: When the platform's terms or policies change in the database, a webhook triggers an asynchronous background pipeline that re-chunks the documents and updates the vector indices without blocking the caller.
• HMAC-SHA256 Authentication: All webhook endpoints validate incoming payloads by computing an HMAC-SHA256 signature using a shared WEBHOOK_SECRET and comparing it to the signature supplied in the X-Webhook-Signature header. This prevents unauthorized calls and payload tampering.

---

Project Structure

src/
├── ai_models/       # Local Sentence-Transformer model weights and configurations
├── api/             # High-level API routing and configuration
├── chatbotRAG/      # Grounded RAG workflows, chunking logic, and prompt templates
├── core/            # Configuration management, db session pools, and error handling
├── models/          # SQLAlchemy database declarations (User, Auction, LegalDocument, etc.)
├── recommendation/  # Recommender services (Trending, QuickPicks, CategoryAffinity)
├── search/          # 7-Step search pipeline, AI Query Parser, and mappers
│   ├── resources/   # Local synonym files (synonyms_base.json)
│   └── services/    # Pipeline services, zero-results fallbacks, typo resolvers
├── shared/          # Core adapters for external systems (Meilisearch, Groq, HF)
└── webhooks/        # HMAC-SHA256 handlers and event synchronization adapters

---

Local Setup & Execution Guide

Follow these steps to run the AllaTre AI Backend in your local environment.

1. Prerequisites

Ensure the following tools are installed:

• Python 3.12+
• Docker & Docker Compose
• MiniConda (Highly recommended for environment isolation)

2. Stand Up Infrastructure Dependencies

Spin up Meilisearch and Redis locally using the pre-configured Docker Compose file:

docker compose -f docker/docker-compose.yml up -d

Verify that Meilisearch is running on http://localhost:7700 and Redis is running on port 6379.

3. Environment Setup & Isolation

Create and activate a new Conda virtual environment:

# Initialize Python 3.12 environment
conda create -n allatre-ai python=3.12 -y
conda activate allatre-ai

# Install all runtime and testing dependencies
pip install -r requirements.txt

4. Configure Environment Variables

Create your local environment file:

cp .env.example .env

Open .env and fill in the parameters, specifically:

• DATABASE_URL: Point to your active PostgreSQL instance.
• MEILI_ADMIN_KEY: Set this to your Meilisearch master key.
• GROQ_API_KEY / HF_API_KEY: Provide tokens for AI query parsing capabilities.

5. Initialize Meilisearch Settings

Before using the search engine, configure Meilisearch settings, search rules, and typographic matching rules. (Hint: Make a call to /api/search/meili/setup or run the index configuration routines upon initial database migrations to configure filters, attributes, and ranking settings).

6. Run the FastAPI Server

Start the server in reload/development mode:

uvicorn src.main:app --reload --port 5000

Upon startup, the application executes the following Lifespan events:

1. Connects to and pre-warms the PostgreSQL database connection pool.
2. Reads and syncs base synonyms from src/search/resources/synonyms_base.json straight into Meilisearch.
3. Loads the local Sentence-Transformers model into memory and executes a warm-up query.
4. Confirms startup: Starting AllaTre-AI v1.0.0.

The interactive API documentation (Swagger UI) is available at http://127.0.0.1:5000/docs.

---