diff --git a/README.md b/README.md index b1f047a..cd9ed64 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,136 @@ -Here is the **formatted and organized** version of your document for the **AI Model Hub Service**: +# ๐Ÿง  Cortex Hub: AI Model Hub Service ---- +[](https://www.python.org/downloads/release/python-3110/) +[](https://github.com/psf/black) +[](https://fastapi.tiangolo.com/) -# **AI Model Hub Service** +Cortex Hub is a modular and scalable API service designed to act as a central gateway to various Large Language Models (LLMs). It features a stateful, session-based chat system with conversational memory, powered by a Retrieval-Augmented Generation (RAG) pipeline for grounding responses in your own data. -This project is a central **hub service** designed to route requests to various **Large Language Models (LLMs)** and manage associated data. It integrates a **relational database (PostgreSQL)** for metadata with a **vector store (FAISS)** for efficient similarity search. +## โœจ Features ---- +* **Conversational Memory**: Engages in stateful conversations using a session-based API. The AI remembers previous messages to provide contextual follow-up answers. +* **Retrieval-Augmented Generation (RAG)**: Ingest documents into a high-speed FAISS vector store to ground the AI's responses in factual, user-provided data. +* **Multi-Provider Support**: Easily integrates with multiple LLM providers (currently DeepSeek and Gemini). +* **Full Document Lifecycle**: Complete API for adding, listing, and deleting documents from the knowledge base. +* **Modern Tech Stack**: Built with FastAPI, Pydantic, SQLAlchemy, and DSPy for a robust, type-safe, and high-performance backend. +* **Containerized**: Fully containerized with Docker and Docker Compose for easy setup and deployment. -## **High-Level Architecture** +----- -The service consists of several main components that work together to process user requests and manage data: +## ๐Ÿš€ Getting Started -* **API Server** - A **FastAPI** application that serves as the primary entry point for all client requests. +You can run the entire application stack (API server and database) using Docker Compose. -* **LLM Router / Orchestrator** - The core logic that determines which LLM handles a request, manages chat history, and orchestrates interactions with the databases. +### Prerequisites -* **Vector Database (FAISS + PostgreSQL)** - A two-part system for data storage: +* **Docker** and **Docker Compose** +* **Python 3.11+** (for local development) +* An API key for at least one supported LLM (DeepSeek, Gemini). - * **PostgreSQL**: Stores relational data like user sessions, chat messages, document metadata, and more. - * **FAISS**: An in-memory index for high-speed vector similarity search. +### 1\. Configuration ---- +The application is configured using a `.env` file for secrets and a `config.yaml` for non-sensitive settings. -## **Database Schema** +First, copy the example environment file: -The schema is designed to store **conversations**, **documents**, and the metadata necessary to link them together. +```bash +cp .env.example .env +``` -### **1. sessions** +Now, open the `.env` file and add your secret API keys: -Stores individual conversations with a user. +``` +# .env +DEEPSEEK_API_KEY="your_deepseek_api_key_here" +GEMINI_API_KEY="your_gemini_api_key_here" +``` -* **Columns**: - `id`, `user_id`, `title`, `model_name`, `created_at`, `is_archived` +*(You only need to provide a key for the model you intend to use.)* ---- +### 2\. Running with Docker Compose (Recommended) -### **2. messages** +This is the simplest way to get the service running. -Stores each message within a session. +```bash +docker-compose up --build +``` -* **Columns**: - `id`, `session_id`, `sender`, `content`, `created_at`, `model_response_time`, `token_count`, `metadata` +The API server will be available at `http://127.0.0.1:8000`. ---- +### 3\. Running Locally (Alternative) -### **3. documents** +If you prefer to run without Docker: -Stores the original text and metadata of a document for **RAG** (Retrieval-Augmented Generation). +```bash +# Install dependencies +pip install -r requirements.txt -* **Columns**: - `id`, `title`, `text`, `source_url`, `author`, `status`, `created_at`, `user_id` +# Run the server +uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload +``` ---- +----- -### **4. vector\_metadata** +## ๐Ÿ’ฌ Usage -Links a document to its vector representation in the **FAISS index**. +### Interactive Chat Script -* **Columns**: - `id`, `document_id`, `faiss_index`, `session_id`, `embedding_model` +The easiest way to interact with the service is by using the provided chat script. It handles starting the server, creating a session, and managing the conversation. ---- +In your terminal, simply run: -## **Technology Stack** +```bash +bash run_chat.sh +``` -* **API Framework**: FastAPI (Python) -* **LLM Integration**: LangChain (or similar) -* **Relational Database**: PostgreSQL -* **Vector Store**: FAISS -* **ORM**: SQLAlchemy -* **Testing Framework**: Pytest +You will be prompted to enter your questions in a continuous loop. Type `exit` to end the session and shut down the server. ---- +### API Documentation -## **Running Tests** +Once the server is running, interactive API documentation (powered by Swagger UI) is automatically available at: -To ensure the database models work correctly, a set of tests is provided using **an in-memory SQLite database**. +* **[http://127.0.0.1:8000/docs](https://www.google.com/search?q=http://127.0.0.1:8000/docs)** -### **Steps to Run Tests** +## From this page, you can explore and execute all API endpoints directly from your browser -1. **Navigate to the project root.** +## ๐Ÿงช Running Tests -2. **Set up your environment and install dependencies:** +The project includes a comprehensive test suite using `pytest`. - ```bash - pip install -e .[test] - ``` +### Unit Tests - This installs the project in *editable mode* along with the test dependencies defined in `pyproject.toml`. +These tests cover individual components in isolation and use mocks for external services and the database. -3. **Run tests using Pytest:** +```bash +pytest tests/ +``` - ```bash - pytest - ``` +### Integration Tests - Pytest will automatically discover and run all tests in the `tests/` directory. +These tests run against a live instance of the server to verify the end-to-end functionality of the API. The script handles starting and stopping the server for you. ---- +```bash +bash run_integration_tests.sh +``` -Let me know if you want this converted to **Markdown**, **PDF**, or **documentation site format (e.g., Sphinx or MkDocs)**. +----- + +## ๐Ÿ›๏ธ Project Structure + +The project follows a standard, scalable structure for modern Python applications. + +``` +. +โ”œโ”€โ”€ app/ # Main application package +โ”‚ย ย  โ”œโ”€โ”€ api/ # API layer: routes, schemas, dependencies +โ”‚ย ย  โ”œโ”€โ”€ core/ # Core business logic: services, pipelines, providers +โ”‚ย ย  โ”œโ”€โ”€ db/ # Database layer: models, session management +โ”‚ย ย  โ”œโ”€โ”€ app.py # FastAPI application factory +โ”‚ย ย  โ””โ”€โ”€ main.py # Application entry point +โ”œโ”€โ”€ config.yaml # Default configuration +โ”œโ”€โ”€ data/ # Persistent data (SQLite DB, FAISS index) +โ”œโ”€โ”€ integration_tests/ # End-to-end tests +โ”œโ”€โ”€ tests/ # Unit tests +โ”œโ”€โ”€ Dockerfile +โ””โ”€โ”€ docker-compose.yml +```