From c7a129cbead78a7a15ea362a7e1af4d6fb62251f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 13 Nov 2025 06:09:30 +0000 Subject: [PATCH] docs: Add comprehensive API documentation for AI Suggestions endpoints Co-authored-by: dawnsystem <42047891+dawnsystem@users.noreply.github.com> --- docs/API_AI_SUGGESTIONS.md | 441 +++++++++++++++++++++++++++++++++++++ 1 file changed, 441 insertions(+) create mode 100644 docs/API_AI_SUGGESTIONS.md diff --git a/docs/API_AI_SUGGESTIONS.md b/docs/API_AI_SUGGESTIONS.md new file mode 100644 index 000000000..6dd755c39 --- /dev/null +++ b/docs/API_AI_SUGGESTIONS.md @@ -0,0 +1,441 @@ +# AI Suggestions API Documentation + +This document describes the AI Suggestions API endpoints for the IntelliDocs-ngx project. + +## Overview + +The AI Suggestions API allows frontend applications to: +1. Retrieve AI-generated suggestions for document metadata +2. Apply suggestions to documents +3. Reject suggestions (for user feedback) +4. View accuracy statistics for AI model improvement + +## Authentication + +All endpoints require authentication. Include the authentication token in the request headers: + +```http +Authorization: Token +``` + +## Endpoints + +### 1. Get AI Suggestions + +Retrieve AI-generated suggestions for a specific document. + +**Endpoint:** `GET /api/documents/{id}/ai-suggestions/` + +**Parameters:** +- `id` (path parameter): Document ID + +**Response:** +```json +{ + "tags": [ + { + "id": 1, + "name": "Invoice", + "color": "#FF5733", + "confidence": 0.85 + }, + { + "id": 2, + "name": "Important", + "color": "#33FF57", + "confidence": 0.75 + } + ], + "correspondent": { + "id": 5, + "name": "Acme Corporation", + "confidence": 0.90 + }, + "document_type": { + "id": 3, + "name": "Invoice", + "confidence": 0.88 + }, + "storage_path": { + "id": 2, + "name": "Financial Documents", + "path": "/documents/financial/", + "confidence": 0.80 + }, + "custom_fields": [ + { + "field_id": 1, + "field_name": "Invoice Number", + "value": "INV-2024-001", + "confidence": 0.92 + } + ], + "workflows": [ + { + "id": 4, + "name": "Invoice Processing", + "confidence": 0.78 + } + ], + "title_suggestion": { + "title": "Invoice - Acme Corporation - 2024-01-15" + } +} +``` + +**Error Responses:** +- `400 Bad Request`: Document has no content to analyze +- `404 Not Found`: Document not found +- `500 Internal Server Error`: Error generating suggestions + +--- + +### 2. Apply Suggestion + +Apply an AI suggestion to a document and record user feedback. + +**Endpoint:** `POST /api/documents/{id}/apply-suggestion/` + +**Parameters:** +- `id` (path parameter): Document ID + +**Request Body:** +```json +{ + "suggestion_type": "tag", + "value_id": 1, + "confidence": 0.85 +} +``` + +**Suggestion Types:** +- `tag` - Tag assignment +- `correspondent` - Correspondent assignment +- `document_type` - Document type classification +- `storage_path` - Storage path assignment +- `custom_field` - Custom field value +- `workflow` - Workflow assignment +- `title` - Document title + +**For ID-based suggestions (tag, correspondent, document_type, storage_path, workflow):** +```json +{ + "suggestion_type": "correspondent", + "value_id": 5, + "confidence": 0.90 +} +``` + +**For text-based suggestions (title, custom_field):** +```json +{ + "suggestion_type": "title", + "value_text": "New Document Title", + "confidence": 0.80 +} +``` + +**Response:** +```json +{ + "status": "success", + "message": "Tag 'Invoice' applied" +} +``` + +**Error Responses:** +- `400 Bad Request`: Invalid suggestion type or missing value +- `404 Not Found`: Referenced object not found +- `500 Internal Server Error`: Error applying suggestion + +--- + +### 3. Reject Suggestion + +Reject an AI suggestion and record user feedback for model improvement. + +**Endpoint:** `POST /api/documents/{id}/reject-suggestion/` + +**Parameters:** +- `id` (path parameter): Document ID + +**Request Body:** +```json +{ + "suggestion_type": "tag", + "value_id": 2, + "confidence": 0.65 +} +``` + +Same format as apply-suggestion endpoint. + +**Response:** +```json +{ + "status": "success", + "message": "Suggestion rejected and feedback recorded" +} +``` + +**Error Responses:** +- `400 Bad Request`: Invalid request data +- `500 Internal Server Error`: Error recording feedback + +--- + +### 4. AI Suggestion Statistics + +Get accuracy statistics and metrics for AI suggestions. + +**Endpoint:** `GET /api/documents/ai-suggestion-stats/` + +**Response:** +```json +{ + "total_suggestions": 150, + "total_applied": 120, + "total_rejected": 30, + "accuracy_rate": 80.0, + "by_type": { + "tag": { + "total": 50, + "applied": 45, + "rejected": 5, + "accuracy_rate": 90.0 + }, + "correspondent": { + "total": 40, + "applied": 35, + "rejected": 5, + "accuracy_rate": 87.5 + }, + "document_type": { + "total": 30, + "applied": 20, + "rejected": 10, + "accuracy_rate": 66.67 + }, + "storage_path": { + "total": 20, + "applied": 15, + "rejected": 5, + "accuracy_rate": 75.0 + }, + "title": { + "total": 10, + "applied": 5, + "rejected": 5, + "accuracy_rate": 50.0 + } + }, + "average_confidence_applied": 0.82, + "average_confidence_rejected": 0.58, + "recent_suggestions": [ + { + "id": 150, + "document": 42, + "suggestion_type": "tag", + "suggested_value_id": 5, + "suggested_value_text": "", + "confidence": 0.85, + "status": "applied", + "user": 1, + "created_at": "2024-01-15T10:30:00Z", + "applied_at": "2024-01-15T10:30:05Z", + "metadata": {} + } + ] +} +``` + +**Error Responses:** +- `500 Internal Server Error`: Error calculating statistics + +--- + +## Frontend Integration Example + +### React/TypeScript Example + +```typescript +import axios from 'axios'; + +const API_BASE = '/api/documents'; + +interface AISuggestions { + tags?: Array<{id: number; name: string; confidence: number}>; + correspondent?: {id: number; name: string; confidence: number}; + document_type?: {id: number; name: string; confidence: number}; + // ... other fields +} + +// Get AI suggestions +async function getAISuggestions(documentId: number): Promise { + const response = await axios.get(`${API_BASE}/${documentId}/ai-suggestions/`); + return response.data; +} + +// Apply a suggestion +async function applySuggestion( + documentId: number, + type: string, + valueId: number, + confidence: number +): Promise { + await axios.post(`${API_BASE}/${documentId}/apply-suggestion/`, { + suggestion_type: type, + value_id: valueId, + confidence: confidence + }); +} + +// Reject a suggestion +async function rejectSuggestion( + documentId: number, + type: string, + valueId: number, + confidence: number +): Promise { + await axios.post(`${API_BASE}/${documentId}/reject-suggestion/`, { + suggestion_type: type, + value_id: valueId, + confidence: confidence + }); +} + +// Get statistics +async function getStatistics() { + const response = await axios.get(`${API_BASE}/ai-suggestion-stats/`); + return response.data; +} + +// Usage example +async function handleDocument(documentId: number) { + try { + // Get suggestions + const suggestions = await getAISuggestions(documentId); + + // Show suggestions to user + if (suggestions.tags) { + suggestions.tags.forEach(tag => { + console.log(`Suggested tag: ${tag.name} (${tag.confidence * 100}%)`); + }); + } + + // User accepts a tag suggestion + if (suggestions.tags && suggestions.tags.length > 0) { + const tag = suggestions.tags[0]; + await applySuggestion(documentId, 'tag', tag.id, tag.confidence); + console.log('Tag applied successfully'); + } + + } catch (error) { + console.error('Error handling AI suggestions:', error); + } +} +``` + +--- + +## Database Schema + +### AISuggestionFeedback Model + +Stores user feedback on AI suggestions for accuracy tracking and model improvement. + +**Fields:** +- `id` (BigAutoField): Primary key +- `document` (ForeignKey): Reference to Document +- `suggestion_type` (CharField): Type of suggestion (tag, correspondent, etc.) +- `suggested_value_id` (IntegerField, nullable): ID of suggested object +- `suggested_value_text` (TextField): Text representation of suggestion +- `confidence` (FloatField): AI confidence score (0.0 to 1.0) +- `status` (CharField): 'applied' or 'rejected' +- `user` (ForeignKey, nullable): User who provided feedback +- `created_at` (DateTimeField): When suggestion was created +- `applied_at` (DateTimeField): When feedback was recorded +- `metadata` (JSONField): Additional metadata + +**Indexes:** +- `(document, suggestion_type)` +- `(status, created_at)` +- `(suggestion_type, status)` + +--- + +## Best Practices + +1. **Confidence Thresholds:** + - High confidence (≥ 0.80): Can be auto-applied + - Medium confidence (0.60-0.79): Show to user for review + - Low confidence (< 0.60): Log but don't suggest + +2. **Error Handling:** + - Always handle 400, 404, and 500 errors gracefully + - Show user-friendly error messages + - Log errors for debugging + +3. **Performance:** + - Cache suggestions when possible + - Use pagination for statistics endpoint if needed + - Batch apply/reject operations when possible + +4. **User Experience:** + - Show confidence scores to users + - Allow users to modify suggestions before applying + - Provide feedback on applied/rejected actions + - Show statistics to demonstrate AI improvement over time + +5. **Privacy:** + - Only authenticated users can access suggestions + - Users can only see suggestions for documents they have access to + - Feedback is tied to user accounts for accountability + +--- + +## Troubleshooting + +### No suggestions returned +- Verify document has content (document.content is not empty) +- Check if AI scanner is enabled in settings +- Verify ML models are loaded correctly + +### Suggestions not being applied +- Check user permissions on the document +- Verify the suggested object (tag, correspondent, etc.) still exists +- Check application logs for detailed error messages + +### Statistics showing 0 accuracy +- Ensure users are applying or rejecting suggestions +- Check database for AISuggestionFeedback entries +- Verify feedback is being recorded with correct status + +--- + +## Future Enhancements + +Potential improvements for future versions: + +1. Bulk operations (apply/reject multiple suggestions at once) +2. Suggestion confidence threshold configuration per user +3. A/B testing different AI models +4. Machine learning model retraining based on feedback +5. Suggestion explanations (why AI made this suggestion) +6. Custom suggestion rules per user or organization +7. Integration with external AI services +8. Real-time suggestions via WebSocket + +--- + +## Support + +For issues or questions: +- GitHub Issues: https://github.com/dawnsystem/IntelliDocs-ngx/issues +- Documentation: https://docs.paperless-ngx.com +- Community: Matrix chat or forum + +--- + +*Last updated: 2024-11-13* +*API Version: 1.0*