README.md

metadata

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

   cd /mnt/BA1E86C91E867DDF/ubuntu_folder/python/fastapi/dummy_add-det_summ_ser
   

2. Create and activate virtual environment (if not already done)

   python -m venv .venv
   source .venv/bin/activate  # On Linux/Mac
   

3. Install dependencies

   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:

python app.py

Or using uvicorn directly:

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:

{
  "entity_urn": "string",
  "content": "string"
}

Response:

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

Example:

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:

{
  "entity_urn": "string",
  "content": "string"
}

Response:

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

Example:

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:

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:

export OPENAI_API_KEY="your_openai_api_key_here"

Then run the test script to verify the endpoints:

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