Spaces:

snvskiit
/

content_processor

Sleeping

satishsnv

updated readme

20929ce over 1 year ago

5.92 kB

---
title: Address Detection and Summarization API
emoji: 🏠📝
colorFrom: blue
colorTo: green
sdk: docker
sdk_version: "4.40.0"
app_file: app.py
pinned: false
---
# Address Detection and Summarization API

A FastAPI application that provides two main endpoints for address detection and text summarization with sentiment analysis using OpenAI's GPT models.

## Features

- **Address Detection**: Extracts addresses from text content
- **Text Summarization**: Generates summaries with sentiment analysis
- **OpenAI Integration**: Uses GPT-4 for natural language processing
- **Header-based Authentication**: OpenAI API key passed via `x-api-key` header
- **RESTful API**: Clean and simple API endpoints

## Installation

1. **Clone or navigate to the project directory**
   ```bash
   cd /mnt/BA1E86C91E867DDF/ubuntu_folder/python/fastapi/dummy_add-det_summ_ser
   ```

2. **Create and activate virtual environment** (if not already done)
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Linux/Mac
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

## Configuration

**Important**: This API requires the OpenAI API key to be passed in the `x-api-key` request header, not as environment variables.

## Running the Application

Start the FastAPI server:

```bash
python app.py
```

Or using uvicorn directly:

```bash
uvicorn app:app --host 0.0.0.0 --port 7860 --reload
```

The API will be available at: http://localhost:7860 (or http://localhost:8500 for local development)

## API Documentation

Once running, visit:
- Interactive API docs: http://localhost:7860/docs (or :8500 for local)
- ReDoc documentation: http://localhost:7860/redoc

## API Endpoints

### 1. Address Detection

**POST** `/address-detection`

Detects and extracts addresses from the provided text content.

**Headers:**
```
Content-Type: application/json
x-api-key: your_openai_api_key_here
```

**Request Body:**
```json
{
  "entity_urn": "string",
  "content": "string"
}
```

**Response:**
```json
{
  "message": "success|failure",
  "result": "address1 || address2 || address3",
  "action_type": "detect_address",
  "entity_urn": "string",
  "sentiment": null
}
```

**Example:**
```bash
curl -X POST "http://localhost:7860/address-detection" \
     -H "Content-Type: application/json" \
     -H "x-api-key: your_openai_api_key_here" \
     -d '{
       "entity_urn": "test_001",
       "content": "Please send the package to 123 Main Street, New York, NY 10001"
     }'
```

### 2. Text Summarization

**POST** `/summarize`

Generates a summary of the text content along with sentiment analysis.

**Headers:**
```
Content-Type: application/json
x-api-key: your_openai_api_key_here
```

**Request Body:**
```json
{
  "entity_urn": "string",
  "content": "string"
}
```

**Response:**
```json
{
  "message": "success|failure",
  "result": "summary text",
  "action_type": "summarize",
  "entity_urn": "string",
  "sentiment": {
    "label": "positive|negative",
    "score": -1.0 to 1.0
  }
}
```

**Example:**
```bash
curl -X POST "http://localhost:7860/summarize" \
     -H "Content-Type: application/json" \
     -H "x-api-key: your_openai_api_key_here" \
     -d '{
       "entity_urn": "test_002",
       "content": "I love this product! It exceeded my expectations..."
     }'
```

## Deployment

This API is designed for easy deployment to Hugging Face Spaces using Docker.

### For Hugging Face Spaces:
1. Upload: `app.py`, `Dockerfile`, `requirements.txt`, `README.md`
2. The service will automatically run on port 7860
3. API will be available at: `https://your-space-name.hf.space`

### For Local Development:
```bash
python app.py  # Runs on port 8500
```

See `DEPLOY.md` for detailed deployment instructions.

## Testing

Before running tests, make sure to set your OpenAI API key as an environment variable:

```bash
export OPENAI_API_KEY="your_openai_api_key_here"
```

Then run the test script to verify the endpoints:

```bash
python test.py
```

Make sure the server is running before executing the tests.

The test script will also test error handling by making requests without the API key header.

## Project Structure

```
dummy_add-det_summ_ser/
├── app.py               # Main FastAPI application
├── test.py              # Test script for API endpoints  
├── requirements.txt     # Python dependencies
├── Dockerfile           # Docker configuration for deployment
├── README.md            # This file
├── DEPLOY.md            # Deployment instructions
└── .gitignore           # Git ignore patterns
```

## Dependencies

- **FastAPI**: Web framework for building APIs (v0.115.14)
- **Uvicorn**: ASGI server for running FastAPI (v0.34.3)
- **Pydantic**: Data validation using Python type annotations (v2.11.7)
- **OpenAI**: Official OpenAI Python client (v1.92.1)
- **python-dotenv**: Load environment variables from .env file (v1.1.1)
- **httpx**: Modern HTTP client library for testing (v0.28.1)

## Error Handling

The API includes comprehensive error handling:
- **Missing API Key**: Returns 422 error if `x-api-key` header is not provided
- **Invalid API Key**: Returns 500 error if the OpenAI API key is invalid
- **OpenAI API connection failures**: Returns 500 error with descriptive message
- **Empty content validation**: Returns failure response with appropriate message
- **Malformed requests**: Returns 422 error for validation issues

All errors return appropriate HTTP status codes and descriptive error messages.

## Notes

- **API Key Security**: The OpenAI API key must be passed in the `x-api-key` header for each request
- The API uses GPT-4o model by default
- Sentiment scores range from -1.0 (most negative) to 1.0 (most positive)
- Address detection returns addresses concatenated with ' || ' separator
- The `entity_urn` field is used instead of `entity_id` for better naming convention

	---
	title: Address Detection and Summarization API
	emoji: 🏠📝
	colorFrom: blue
	colorTo: green
	sdk: docker
	sdk_version: "4.40.0"
	app_file: app.py
	pinned: false
	---

	# Address Detection and Summarization API

	A FastAPI application that provides two main endpoints for address detection and text summarization with sentiment analysis using OpenAI's GPT models.

	## Features

	- Address Detection: Extracts addresses from text content
	- Text Summarization: Generates summaries with sentiment analysis
	- OpenAI Integration: Uses GPT-4 for natural language processing
	- Header-based Authentication: OpenAI API key passed via `x-api-key` header
	- RESTful API: Clean and simple API endpoints

	## Installation

	1. Clone or navigate to the project directory
	```bash
	cd /mnt/BA1E86C91E867DDF/ubuntu_folder/python/fastapi/dummy_add-det_summ_ser
	```

	2. Create and activate virtual environment (if not already done)
	```bash
	python -m venv .venv
	source .venv/bin/activate # On Linux/Mac
	```

	3. Install dependencies
	```bash
	pip install -r requirements.txt
	```

	## Configuration

	Important: This API requires the OpenAI API key to be passed in the `x-api-key` request header, not as environment variables.

	## Running the Application

	Start the FastAPI server:

	```bash
	python app.py
	```

	Or using uvicorn directly:

	```bash
	uvicorn app:app --host 0.0.0.0 --port 7860 --reload
	```

	The API will be available at: http://localhost:7860 (or http://localhost:8500 for local development)

	## API Documentation

	Once running, visit:
	- Interactive API docs: http://localhost:7860/docs (or :8500 for local)
	- ReDoc documentation: http://localhost:7860/redoc

	## API Endpoints

	### 1. Address Detection

	POST `/address-detection`

	Detects and extracts addresses from the provided text content.

	Headers:
	```
	Content-Type: application/json
	x-api-key: your_openai_api_key_here
	```

	Request Body:
	```json
	{
	"entity_urn": "string",
	"content": "string"
	}
	```

	Response:
	```json
	{
	"message": "success\|failure",
	"result": "address1 \|\| address2 \|\| address3",
	"action_type": "detect_address",
	"entity_urn": "string",
	"sentiment": null
	}
	```

	Example:
	```bash
	curl -X POST "http://localhost:7860/address-detection" \
	-H "Content-Type: application/json" \
	-H "x-api-key: your_openai_api_key_here" \
	-d '{
	"entity_urn": "test_001",
	"content": "Please send the package to 123 Main Street, New York, NY 10001"
	}'
	```

	### 2. Text Summarization

	POST `/summarize`

	Generates a summary of the text content along with sentiment analysis.

	Headers:
	```
	Content-Type: application/json
	x-api-key: your_openai_api_key_here
	```

	Request Body:
	```json
	{
	"entity_urn": "string",
	"content": "string"
	}
	```

	Response:
	```json
	{
	"message": "success\|failure",
	"result": "summary text",
	"action_type": "summarize",
	"entity_urn": "string",
	"sentiment": {
	"label": "positive\|negative",
	"score": -1.0 to 1.0
	}
	}
	```

	Example:
	```bash
	curl -X POST "http://localhost:7860/summarize" \
	-H "Content-Type: application/json" \
	-H "x-api-key: your_openai_api_key_here" \
	-d '{
	"entity_urn": "test_002",
	"content": "I love this product! It exceeded my expectations..."
	}'
	```

	## Deployment

	This API is designed for easy deployment to Hugging Face Spaces using Docker.

	### For Hugging Face Spaces:
	1. Upload: `app.py`, `Dockerfile`, `requirements.txt`, `README.md`
	2. The service will automatically run on port 7860
	3. API will be available at: `https://your-space-name.hf.space`

	### For Local Development:
	```bash
	python app.py # Runs on port 8500
	```

	See `DEPLOY.md` for detailed deployment instructions.

	## Testing

	Before running tests, make sure to set your OpenAI API key as an environment variable:

	```bash
	export OPENAI_API_KEY="your_openai_api_key_here"
	```

	Then run the test script to verify the endpoints:

	```bash
	python test.py
	```

	Make sure the server is running before executing the tests.

	The test script will also test error handling by making requests without the API key header.

	## Project Structure

	```
	dummy_add-det_summ_ser/
	├── app.py # Main FastAPI application
	├── test.py # Test script for API endpoints
	├── requirements.txt # Python dependencies
	├── Dockerfile # Docker configuration for deployment
	├── README.md # This file
	├── DEPLOY.md # Deployment instructions
	└── .gitignore # Git ignore patterns
	```

	## Dependencies

	- FastAPI: Web framework for building APIs (v0.115.14)
	- Uvicorn: ASGI server for running FastAPI (v0.34.3)
	- Pydantic: Data validation using Python type annotations (v2.11.7)
	- OpenAI: Official OpenAI Python client (v1.92.1)
	- python-dotenv: Load environment variables from .env file (v1.1.1)
	- httpx: Modern HTTP client library for testing (v0.28.1)

	## Error Handling

	The API includes comprehensive error handling:
	- Missing API Key: Returns 422 error if `x-api-key` header is not provided
	- Invalid API Key: Returns 500 error if the OpenAI API key is invalid
	- OpenAI API connection failures: Returns 500 error with descriptive message
	- Empty content validation: Returns failure response with appropriate message
	- Malformed requests: Returns 422 error for validation issues

	All errors return appropriate HTTP status codes and descriptive error messages.

	## Notes

	- API Key Security: The OpenAI API key must be passed in the `x-api-key` header for each request
	- The API uses GPT-4o model by default
	- Sentiment scores range from -1.0 (most negative) to 1.0 (most positive)
	- Address detection returns addresses concatenated with ' \|\| ' separator
	- The `entity_urn` field is used instead of `entity_id` for better naming convention