mirror of
https://github.com/SamyRai/turash.git
synced 2025-12-26 23:01:33 +00:00
6347f42e20
- Remove nested git repository from bugulma/frontend/.git - Add all frontend files to main repository tracking - Convert from separate frontend/backend repos to unified monorepo - Preserve all frontend code and development history as tracked files - Eliminate nested repository complexity for simpler development workflow This creates a proper monorepo structure with frontend and backend coexisting in the same repository for easier development and deployment.
251 lines
4.0 KiB
Markdown
251 lines
4.0 KiB
Markdown
# 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' });
|
|
```
|