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.
4.0 KiB
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:
{
"text": "Company name: Acme Corp, Sector: Manufacturing, Description: ..."
}
Response:
{
"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:
{
"name": "Acme Corp",
"sector": "manufacturing",
"description": "...",
...
}
3. Analyze Symbiosis
POST /api/ai/analyze/symbiosis
Analyze potential symbiotic relationships for an organization.
Request:
{
"organization_id": "org-123"
}
Response:
{
"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:
{
"organization_name": "Acme Corp"
}
Response:
{
"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:
{
"query": "manufacturing"
}
Response:
["manufacturing companies", "manufacturing sector", "industrial manufacturing"]
6. Generate Organization Description
POST /api/ai/generate/description
Generate a professional organization description.
Request:
{
"name": "Acme Corp",
"sector_key": "manufacturing",
"keywords": "sustainable, green energy, innovation"
}
Response:
{
"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:
{
"landmark": {
"id": "landmark-1",
"name": "Old Factory",
"period": "1920s",
"originalPurpose": "Textile manufacturing",
"currentStatus": "Converted to offices"
}
}
Response:
{
"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:
{
"message": "What is industrial symbiosis?",
"system_instruction": "You are a helpful assistant about industrial symbiosis."
}
Response:
{
"response": "Industrial symbiosis is..."
}
Error Handling
All endpoints should return standard error responses:
{
"error": "Error message",
"code": "ERROR_CODE"
}
Status codes:
400- Bad Request401- Unauthorized500- Internal Server Error
Implementation Notes
- Authentication: All endpoints (except possibly chat) require JWT authentication
- File Uploads: Use
multipart/form-datafor file uploads - Rate Limiting: Consider implementing rate limiting for AI endpoints
- Caching: Consider caching responses where appropriate
- Cost Management: Track and limit AI API usage
Frontend Usage
The frontend uses these endpoints via services/ai-api.ts:
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' });