{"id":29031664,"url":"https://github.com/FredyRivera-dev/RAG-FastAPI-Server","last_synced_at":"2025-12-30T22:23:37.194Z","repository":{"id":300109907,"uuid":"1004386422","full_name":"F4k3r22/RAG-FastAPI-Server","owner":"F4k3r22","description":"RAG-FastAPI-Server is an API server for managing a lightweight Retrieval-Augmented Generation (RAG) database using FastAPI and PostgreSQL (with pgvector for vector similarity search).","archived":false,"fork":false,"pushed_at":"2025-06-19T22:38:48.000Z","size":5,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-19T23:27:11.992Z","etag":null,"topics":["api","api-rest","embeddings","fastapi","openai","pgvector","postgresql","python","rag","semantic-search"],"latest_commit_sha":null,"homepage":"https://riverasolutions.vercel.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/F4k3r22.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-18T14:42:42.000Z","updated_at":"2025-06-19T22:38:52.000Z","dependencies_parsed_at":"2025-06-19T23:37:41.790Z","dependency_job_id":null,"html_url":"https://github.com/F4k3r22/RAG-FastAPI-Server","commit_stats":null,"previous_names":["f4k3r22/rag-fastapi-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/F4k3r22/RAG-FastAPI-Server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/F4k3r22%2FRAG-FastAPI-Server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/F4k3r22%2FRAG-FastAPI-Server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/F4k3r22%2FRAG-FastAPI-Server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/F4k3r22%2FRAG-FastAPI-Server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/F4k3r22","download_url":"https://codeload.github.com/F4k3r22/RAG-FastAPI-Server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/F4k3r22%2FRAG-FastAPI-Server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262044447,"owners_count":23249750,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-rest","embeddings","fastapi","openai","pgvector","postgresql","python","rag","semantic-search"],"created_at":"2025-06-26T10:04:54.249Z","updated_at":"2025-12-30T22:23:37.163Z","avatar_url":"https://github.com/F4k3r22.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RAG-FastAPI-Server\n\n## Overview\n\n**RAG-FastAPI-Server** is an API server for managing a lightweight Retrieval-Augmented Generation (RAG) database using FastAPI and PostgreSQL (with `pgvector` for vector similarity search). It enables storing text data with vector embeddings, efficient similarity search, and management of this data through a simple REST API. All core database logic is encapsulated in the `RAGLocal` class.\n\n**[Article on Medium](https://medium.com/@fredyriveraacevedo13/building-a-fastapi-powered-rag-backend-with-postgresql-pgvector-c239f032508a)** \n\n## Demo Video\n\n\n\nhttps://github.com/user-attachments/assets/9fe633a2-a88e-454e-b84b-99c6cfd87e32\n\n\n\n---\n\n## Features\n\n- **Create Indexed Tables**: Create new tables with an indexed vector column for embedding-based search.\n- **Store RAG Items**: Insert text and its embedding vector into a specified table.\n- **Similarity Search**: Retrieve the most similar documents to a given embedding (`cosine` or `euclidean` similarity).\n- **RESTful API**: Interface with your database using HTTP POST requests, powered by FastAPI.\n- **Database Handling**: Clean management of database connections and transactions.\n\n---\n\n## File Structure\n\n```\n.\n├── main.py\n└── RAGLocal/\n    ├── __init__.py\n    └── rag.py\n```\n\n### Main Components\n\n#### `main.py`\n\n- FastAPI app exposing the REST API.\n- Loads environment variables for database credentials.\n- Defines Pydantic models for payload structure.\n- Endpoints:\n  - `POST /rag/{dbname}/create/index`: Create a table + vector index.\n  - `POST /rag/{dbname}/add/rag`: Insert a new document and its embedding.\n  - `POST /rag/{dbname}/query`: Retrieve most similar documents to a query embedding.\n- Instantiates a `RAGLocal` object per request to perform operations.\n\n#### `RAGLocal/rag.py`\n\n- Implements `RAGLocal`, the core database management class.\n- Responsible for:\n  - Connecting to PostgreSQL using `psycopg2` and handling credentials.\n  - Creating tables and ivfflat vector indices for similarity search.\n  - Inserting new records with a text and embedding.\n  - Querying for top-K most similar embeddings, supporting \"cosine\" and \"euclidean\" similarity.\n- Handles connections safely (using context manager and explicit close).\n- Handles transaction commits and rollbacks.\n\n#### `RAGLocal/__init__.py`\n\n- Imports and exposes the `RAGLocal` class for package usage.\n\n---\n\n## API Usage\n\n### 1. Create Index\n\nCreate a table for storing items with embeddings and a vector similarity index.\n\n- **Endpoint**: `POST /rag/{dbname}/create/index`\n- **Payload**:\n  ```json\n  {\n    \"name_index\": \"table_name\",\n    \"content_name\": \"column_name\",\n    \"embedding_dim\": 1536,\n    \"type_index\": \"cos\" // or \"euclidean\"\n  }\n  ```\n- **Returns**: `{ \"status\": \"index_created\", \"table\": \"...\" }`\n\n### 2. Add an Item\n\nAdd a new document and its embedding to a table.\n\n- **Endpoint**: `POST /rag/{dbname}/add/rag`\n- **Payload**:\n  ```json\n  {\n    \"table_name\": \"table_name\",\n    \"content_column\": \"column_name\",\n    \"content\": \"This is the text.\",\n    \"embedding\": [0.12, 0.85, ...] // Same length as embedding_dim\n  }\n  ```\n- **Returns**: `{ \"status\": \"item_added\", \"id\": ... }`\n\n### 3. Query for Similar Documents\n\nFind the top K most similar items for the given embedding.\n\n- **Endpoint**: `POST /rag/{dbname}/query`\n- **Payload**:\n  ```json\n  {\n    \"table_name\": \"table_name\",\n    \"content_column\": \"column_name\",\n    \"query_embedding\": [0.11, 0.87, ...],\n    \"top_k\": 5,\n    \"type_index\": \"cos\" // or \"euclidean\"\n  }\n  ```\n- **Returns**:\n  ```json\n  {\n    \"status\": \"success\",\n    \"results\": [\n      { \"id\": 1, \"content\": \"...\", \"score\": 0.9987 },\n      ...\n    ]\n  }\n  ```\n\n---\n\n## How It Works\n\n- The server loads database credentials from a `.env` file.\n- For each API call, a `RAGLocal` instance is created to perform the necessary DB operations.\n- All vector operations rely on PostgreSQL with the `pgvector` extension for efficient vector storage and search using ivfflat indices.\n- Similarity can be switched between cosine (`\u003c#\u003e`) and euclidean (`\u003c-\u003e`) at index creation/query time.\n\n---\n\n## Key Python Functions\n\n### In `main.py`:\n- **get_rag**: Helper to instantiate `RAGLocal` with DB credentials.\n- **rag_index**: Calls `create_index` to set up a new table and similarity index.\n- **add_rag**: Calls `add_rag` to insert a text+embedding pair.\n- **query_rag**: Calls `query` to retrieve the most similar items.\n\n### In `RAGLocal/rag.py`:\n- **RAGLocal.create_index**: Creates a table for your content and builds a vector similarity index.\n- **RAGLocal.add_rag**: Inserts a new row with text and embedding; returns its DB id.\n- **RAGLocal.query**: Queries the table for top-K matches, computing similarity scores.\n- **Database Utilities** (connect, commit, close): Handle DB connections/transactions robustly.\n\n---\n\n## Requirements\n\n- Python 3.8+\n- PostgreSQL with `pgvector` extension enabled\n- `psycopg2`, `fastapi`, `uvicorn`, `pydantic`, `python-dotenv`\n\n---\n\n## Example: Running the API\n\n1. Set up a PostgreSQL DB and install the `pgvector` extension.\n2. Put your credentials in a `.env` file:\n   ```\n   DB_USER=your_user\n   DB_PASSWORD=your_pass\n   DB_HOST=localhost\n   DB_PORT=5432\n   ```\n3. Start the server:\n   ```\n   uvicorn main:app --host 0.0.0.0 --port 5500\n   ```\n4. Use tools like `curl`, `httpie`, or Postman to interact with the API endpoints.\n\n---\n\n## Security Considerations\n\n- Do **not** expose your database credentials publicly.\n- Always use parameterized queries (as done in this code) to avoid SQL injection.\n- Monitor who has access to your server and databases.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFredyRivera-dev%2FRAG-FastAPI-Server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFredyRivera-dev%2FRAG-FastAPI-Server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFredyRivera-dev%2FRAG-FastAPI-Server/lists"}