CrocoIT Agentic RAG API

A FastAPI backend for a retrieval-augmented customer-support assistant. The application retrieves relevant CrocoIT website content from PostgreSQL with pgvector, delegates response generation to a CrewAI agent powered by Google Gemini, stores conversation history, and supports company-scoped file uploads.

Project status: Active development. The API is suitable for local development and experimentation; review the production considerations before deploying it publicly.

Features

• Retrieval-augmented responses grounded in stored website content
• CrewAI agent orchestration with Google Gemini
• Semantic search using 384-dimensional Hugging Face embeddings and pgvector
• Persistent users, conversations, and message history
• Multi-file uploads through Swagger UI or multipart HTTP requests
• Automatic company creation when an upload omits company_id
• Company-specific local file storage
• SQLAlchemy models and Alembic migrations
• Interactive OpenAPI documentation provided by FastAPI

Architecture

flowchart LR
    User[API client] --> API[FastAPI]

    API --> Chat[Chat controller]
    Chat --> Embed[Hugging Face embeddings]
    Embed --> VectorDB[(PostgreSQL + pgvector)]
    VectorDB --> Agent[CrewAI support agent]
    Agent --> Gemini[Google Gemini]
    Gemini --> Chat
    Chat --> History[(Clients and chats)]

    API --> Upload[File controller]
    Upload --> CompanyDB[(Companies and file metadata)]
    Upload --> Disk[Companies/company_id]

Loading

The project follows a layered structure:

• Routes define HTTP inputs and response models.
• Controllers coordinate business logic and transactions.
• Repositories perform database persistence operations.
• Models define SQLAlchemy tables and relationships.
• Schemas define Pydantic API contracts.

Technology Stack

Area	Technology
API	FastAPI, Uvicorn
Agent orchestration	CrewAI
Language model	Google Gemini through CrewAI LLM
Embeddings	sentence-transformers/all-MiniLM-L6-v2
Database	PostgreSQL with pgvector
ORM and migrations	SQLAlchemy, Alembic
Validation	Pydantic
Website extraction	Requests, Beautiful Soup

Project Structure

.
├── app/
│   ├── Agent/              # Agent, task, and retrieval configuration
│   ├── Controllers/        # Chat, user, and upload workflows
│   ├── Core/               # Environment-based configuration
│   ├── Database/           # Engine and session management
│   ├── Model/              # SQLAlchemy models
│   ├── repositories/       # Database access layer
│   ├── routes/             # FastAPI routers
│   ├── Schemas/            # Pydantic request/response schemas
│   ├── tools/              # Scraper and ingestion notebook
│   └── app.py              # FastAPI application entry point
├── alembic/                # Database migrations
├── Tutorial/               # Experimental notebooks
├── Companies/              # Runtime upload storage; created as needed
├── .env.example            # Environment variable template
├── alembic.ini             # Alembic configuration
└── requirements.txt        # Pinned Python dependencies

Prerequisites

• Python 3.10 or newer
• PostgreSQL with the pgvector extension
• A Google Gemini API key
• Git

The embedding model is downloaded from Hugging Face when the agent module is first loaded, so the first application startup requires network access unless the model is already cached.

Getting Started

1. Clone the repository

git clone https://github.com/Youssef3082004/Agantic_RAG.git
cd Agantic_RAG

2. Create a virtual environment

Linux or macOS:

python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1

3. Install dependencies

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

4. Configure the environment

Copy the example file:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

The current settings class requires all of the following variables:

DATABASE_URL="postgresql+psycopg://postgres:password@localhost:5432/postgres"
Gimini_API_KEY="your_google_gemini_key"
Groq_API_KEY="unused_or_configured_key"
Agentops_API_KEY="unused_or_configured_key"
Tavily_API_KEY="unused_or_configured_key"
Scrapegraph_API_KEY="unused_or_configured_key"

Gimini_API_KEY is intentionally shown with the spelling currently used by the source code. Renaming it requires updating app/Core/config.py and app/Agent/Agent.py as well.

Never commit the populated .env file.

5. Prepare PostgreSQL

Create the database and enable pgvector:

CREATE EXTENSION IF NOT EXISTS vector;

Ensure that DATABASE_URL in .env and sqlalchemy.url in alembic.ini target the intended database. Apply the checked-in migrations from the project root:

PYTHONPATH=app alembic upgrade head

Review generated and existing migrations before applying them to shared or production data.

6. Run the API

The application currently uses imports relative to the app directory. From the repository root, start it with:

uvicorn app:app --app-dir app --reload --host 0.0.0.0 --port 8000

Open the documentation:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc
• OpenAPI JSON: http://127.0.0.1:8000/openapi.json

API Reference

Health check

GET /Health/

curl http://127.0.0.1:8000/Health/

Response:

{
  "Health": "Server is on!"
}

Ask the support agent

POST /chatbot/Ask

Query parameter	Type	Required	Description
question	string	Yes	The customer's message
chat_id	UUID string	No	Continue an existing conversation
user_id	integer	No	Associate the request with an existing user

Start a conversation:

curl -X POST \
  "http://127.0.0.1:8000/chatbot/Ask?question=What%20services%20do%20you%20provide%3F"

Example response:

{
  "question": "What services do you provide?",
  "answer": "The assistant response appears here.",
  "chat_id": "3fdb5321-8f3f-4df4-a62f-c90ccfba96e0",
  "new_chat": true
}

Get a user's chat data

GET /DB/get_user?user_id=1

curl "http://127.0.0.1:8000/DB/get_user?user_id=1"

Upload company files

POST /files/upload
Content-Type: multipart/form-data

Input	Location	Required	Description
files	Form data	Yes	One or more uploaded files
company_id	Query	No	Existing company receiving the files

When company_id is omitted, the application creates a company, obtains its auto-incremented ID, and returns that ID in the response. When an ID is provided, it must identify an existing company; otherwise the endpoint returns HTTP 404.

Create a company automatically and upload files:

curl -X POST "http://127.0.0.1:8000/files/upload" \
  -F "files=@./document.pdf" \
  -F "files=@./notes.txt"

Upload to an existing company:

curl -X POST "http://127.0.0.1:8000/files/upload?company_id=1" \
  -F "files=@./document.pdf"

Example response:

{
  "company_id": 1,
  "files": [
    {
      "file_id": 1,
      "file_name": "document.pdf"
    }
  ]
}

Uploaded content is written to Companies/<company_id>/. Filenames are sanitized, duplicate names within one request are rejected, and existing files are not overwritten. Database failures trigger rollback and cleanup of files created during the request.

For a graphical file picker, open /docs, expand POST /files/upload, select Try it out, and use the file control to choose one or multiple files.

Retrieval Workflow

For each chatbot request, the application:

1. Converts the question into a 384-dimensional embedding.
2. Calculates cosine distance against entries in CrocoITKB.
3. Retrieves the five closest knowledge chunks.
4. Supplies the retrieved text and conversation context to the CrewAI agent.
5. Generates a response with Gemini.
6. Persists the conversation in PostgreSQL.

The knowledge-base ingestion workflow is currently maintained in app/tools/PGvector.ipynb. It scrapes website text, chunks it, generates embeddings, and inserts them into CrocoITKB. Treat the notebooks as development utilities and review their paths and database target before executing write cells.

Database Model

Table	Purpose
Client	Customer identity
Chats	Conversation title and JSONB message history
CrocoITKB	Website text and 384-dimensional vectors
Companies	Auto-incremented company identity
Files	Uploaded filename and related company ID

Deleting a company is configured to cascade to its file metadata. Physical files on disk require separate lifecycle handling.

Development

Create a migration after changing SQLAlchemy models:

PYTHONPATH=app alembic revision --autogenerate -m "describe the change"

Apply migrations:

PYTHONPATH=app alembic upgrade head

Compile the application to catch syntax errors:

python -m compileall -q app

Production Considerations

Before production deployment:

• Add authentication and company-level authorization.
• Add upload size limits and an allowlist of supported file types.
• Store uploads in durable object storage instead of local application disk.
• Add rate limiting, structured logging, and monitoring.
• Add unit and integration test coverage.
• Run migrations as a controlled deployment step.
• Avoid running Uvicorn with --reload.
• Move all service configuration into consistently named environment variables.
• Review chat message persistence and error responses.
• Configure database backups and secret rotation.

Security

Do not commit API keys, database passwords, uploaded customer files, or a populated .env file. Validate external content before processing it and ensure that users can access only companies, files, and conversations they are authorized to manage.

Author

Developed by Youssef3082004.