ira/sim-search-api/README.md

Sim-Search API

A FastAPI backend for the Sim-Search intelligent research system.

Overview

This API provides a RESTful interface to the Sim-Search system, allowing for:

• Query processing and classification
• Search execution across multiple engines
• Report generation with different detail levels
• User authentication and management

Architecture

The API follows a layered architecture:

1. API Layer: FastAPI routes and endpoints
2. Service Layer: Business logic and integration with Sim-Search
3. Data Layer: Database models and session management

Setup

Prerequisites

• Python 3.8+
• Sim-Search system installed and configured
• API keys for search engines (if using external search engines)

Installation

1. Clone the repository:

git clone <repository-url>
cd sim-search-api

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Create a .env file based on .env.example:

cp .env.example .env

5. Edit the .env file with your configuration settings.

Database Setup

Initialize the database:

alembic upgrade head

Running the API

Start the API server:

python run.py

Or with custom settings:

python run.py --host 0.0.0.0 --port 8000 --reload --debug

API Documentation

Once the server is running, you can access the API documentation at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

API Endpoints

Authentication

• POST /api/v1/auth/token: Get an authentication token
• POST /api/v1/auth/register: Register a new user

Query Processing

• POST /api/v1/query/process: Process and enhance a user query
• POST /api/v1/query/classify: Classify a query by type and intent

Search Execution

• POST /api/v1/search/execute: Execute a search with optional parameters
• GET /api/v1/search/engines: Get available search engines
• GET /api/v1/search/history: Get user's search history
• GET /api/v1/search/{search_id}: Get results for a specific search
• DELETE /api/v1/search/{search_id}: Delete a search from history

Report Generation

• POST /api/v1/report/generate: Generate a report from search results
• GET /api/v1/report/list: Get a list of user's reports
• GET /api/v1/report/{report_id}: Get a specific report
• DELETE /api/v1/report/{report_id}: Delete a report
• GET /api/v1/report/{report_id}/download: Download a report in specified format

Development

Project Structure

sim-search-api/
├── app/
│   ├── api/
│   │   ├── routes/
│   │   │   ├── __init__.py
│   │   │   ├── query.py           # Query processing endpoints
│   │   │   ├── search.py          # Search execution endpoints
│   │   │   ├── report.py          # Report generation endpoints
│   │   │   └── auth.py            # Authentication endpoints
│   │   ├── __init__.py
│   │   └── dependencies.py         # API dependencies (auth, rate limiting)
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py              # API configuration
│   │   └── security.py            # Security utilities
│   ├── db/
│   │   ├── __init__.py
│   │   ├── session.py             # Database session
│   │   └── models.py              # Database models for reports, searches
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── query.py               # Query schemas
│   │   ├── search.py              # Search result schemas
│   │   └── report.py              # Report schemas
│   ├── services/
│   │   ├── __init__.py
│   │   ├── query_service.py       # Query processing service
│   │   ├── search_service.py      # Search execution service
│   │   └── report_service.py      # Report generation service
│   └── main.py                    # FastAPI application
├── alembic/                       # Database migrations
├── .env.example                   # Environment variables template
└── requirements.txt               # Dependencies

Running Tests

pytest

License

MIT License