# Backend AI Endpoints Specification

This document specifies the AI/LLM endpoints that the frontend expects from the backend. The frontend is now "dumb" and just calls these endpoints.

## Endpoints

All endpoints require authentication (Bearer token) except where noted.

### Base Path

All AI endpoints are under `/api/ai/`

### 1. Extract Data from Text

**POST** `/api/ai/extract/text`

Extract structured organization data from text.

**Request:**

```json
{
  "text": "Company name: Acme Corp, Sector: Manufacturing, Description: ..."
}
```

**Response:**

```json
{
  "name": "Acme Corp",
  "sector": "manufacturing",
  "description": "...",
  "website": "https://acme.com",
  ...
}
```

### 2. Extract Data from File

**POST** `/api/ai/extract/file`

Extract structured organization data from an image file.

**Request:**

- Content-Type: `multipart/form-data`
- Body: `file` (File/Blob)

**Response:**

```json
{
  "name": "Acme Corp",
  "sector": "manufacturing",
  "description": "...",
  ...
}
```

### 3. Analyze Symbiosis

**POST** `/api/ai/analyze/symbiosis`

Analyze potential symbiotic relationships for an organization.

**Request:**

```json
{
  "organization_id": "org-123"
}
```

**Response:**

```json
{
  "matches": [
    {
      "partner_id": "org-456",
      "partner_name": "Partner Corp",
      "reason": "Can provide waste heat for your processes",
      "score": 0.85
    }
  ]
}
```

### 4. Get Web Intelligence

**POST** `/api/ai/web-intelligence`

Get web intelligence about an organization.

**Request:**

```json
{
  "organization_name": "Acme Corp"
}
```

**Response:**

```json
{
  "text": "Acme Corp is a leading manufacturer...",
  "sources": [
    {
      "uri": "https://example.com/article",
      "title": "Article Title"
    }
  ]
}
```

### 5. Get Search Suggestions

**POST** `/api/ai/search-suggestions`

Get search suggestions based on query.

**Request:**

```json
{
  "query": "manufacturing"
}
```

**Response:**

```json
["manufacturing companies", "manufacturing sector", "industrial manufacturing"]
```

### 6. Generate Organization Description

**POST** `/api/ai/generate/description`

Generate a professional organization description.

**Request:**

```json
{
  "name": "Acme Corp",
  "sector_key": "manufacturing",
  "keywords": "sustainable, green energy, innovation"
}
```

**Response:**

```json
{
  "description": "Acme Corp is a forward-thinking manufacturing company..."
}
```

### 7. Generate Historical Context

**POST** `/api/ai/generate/historical-context`

Generate historical context for a landmark.

**Request:**

```json
{
  "landmark": {
    "id": "landmark-1",
    "name": "Old Factory",
    "period": "1920s",
    "originalPurpose": "Textile manufacturing",
    "currentStatus": "Converted to offices"
  }
}
```

**Response:**

```json
{
  "context": "The Old Factory stands as a testament to..."
}
```

### 8. Chat / Send Message

**POST** `/api/ai/chat`

Send a simple message to the AI.

**Request:**

```json
{
  "message": "What is industrial symbiosis?",
  "system_instruction": "You are a helpful assistant about industrial symbiosis."
}
```

**Response:**

```json
{
  "response": "Industrial symbiosis is..."
}
```

## Error Handling

All endpoints should return standard error responses:

```json
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

Status codes:

- `400` - Bad Request
- `401` - Unauthorized
- `500` - Internal Server Error

## Implementation Notes

1. **Authentication**: All endpoints (except possibly chat) require JWT authentication
2. **File Uploads**: Use `multipart/form-data` for file uploads
3. **Rate Limiting**: Consider implementing rate limiting for AI endpoints
4. **Caching**: Consider caching responses where appropriate
5. **Cost Management**: Track and limit AI API usage

## Frontend Usage

The frontend uses these endpoints via `services/ai-api.ts`:

```typescript
import * as aiApi from './services/ai-api';

// Extract data from text
const data = await aiApi.extractDataFromText({ text: '...' });

// Analyze symbiosis
const matches = await aiApi.analyzeSymbiosis({ organization_id: 'org-123' });
```