---
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