diff --git a/README.md b/README.md index 9dbd6d1..2149920 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,9 @@ A comprehensive AI-powered tool designed to streamline the process of ideation, - **Brand Style Management**: Configure and update brand guidelines through a user-friendly interface - **Training Data Management**: Add successful marketing content to improve the AI over time - **Content Performance Analysis**: Get insights into the potential effectiveness of your content +- **History Tracking**: Keep track of all generated content and user interactions +- **Pagination Support**: Efficiently browse through large datasets of historical content +- **Error Handling**: Robust error handling and user feedback systems ## 📋 Project Overview @@ -23,7 +26,10 @@ The Marketing Assistant AI combines a powerful backend built with FastAPI and a - **Frontend**: Vanilla HTML, CSS, and JavaScript - **AI Models**: Cohere's generation and embedding models - **Vector Database**: FAISS for efficient content similarity search -- **Storage**: Local JSON files for historical marketing data +- **Storage**: + - JSON files for historical marketing data + - SQLite for training data + - FAISS vector store for content similarity search ## 🚀 Getting Started @@ -66,8 +72,7 @@ API_HOST=localhost API_PORT=8000 # Database Configuration -VECTOR_DB_PATH=./data/vector_store -HISTORY_DB_PATH=./data/history.db +DATABASE_URL=sqlite:///./data/training_data.db # Brand Configuration BRAND_NAME=Adriana James @@ -244,4 +249,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file --- -Made with ❤️ for Adriana James \ No newline at end of file +Made with ❤️ for Adriana James diff --git a/data/README.md b/data/README.md index 4b8bea4..7e21606 100644 --- a/data/README.md +++ b/data/README.md @@ -8,6 +8,7 @@ This directory contains the data used by the Marketing Assistant AI system. - **user_queries/**: Stores user queries and requests for analytics and model improvement - **style_guidelines/**: Contains brand tone and voice guidelines - **vector_store/**: Generated vector database for content retrieval (created automatically) +- **db/**: Contains SQLite database files for structured data storage ## File Formats @@ -22,15 +23,16 @@ Past campaign files are stored as JSON with the following structure: "metadata": { "campaign_name": "Name of the campaign", "performance_metrics": { - "metric1": value, - "metric2": value + "open_rate": 0.42, + "click_rate": 0.15, + "conversion_rate": 0.08 }, "content_type": "Same as above", - "added_at": "ISO timestamp", + "added_at": "2024-01-01T12:00:00Z", "training_data": true }, - "document_id": 0, - "timestamp": "ISO timestamp" + "document_id": "unique-identifier", + "timestamp": "2024-01-01T12:00:00Z" } ``` @@ -44,10 +46,13 @@ User query files store information about requests made to the AI: "parameters": { "content_type": "Type of content requested", "tone": "Requested tone", - "length": "Requested length", + "length": "short|medium|long", "include_cta": true|false }, - "timestamp": "ISO timestamp" + "timestamp": "2024-01-01T12:00:00Z", + "generated_content": "The AI-generated content", + "feedback": "Optional user feedback", + "performance_score": 0.95 } ``` @@ -63,12 +68,15 @@ Brand style is stored as a JSON file with the following structure: "taboo_words": ["cheap", "discount", "bargain"], "preferred_terms": { "customers": "clients", - "products": "solutions" - } + "products": "solutions", + "problems": "challenges" + }, + "last_updated": "2024-01-01T12:00:00Z", + "version": "1.0" } ``` -## Adding New Data +## Data Management ### Adding Past Campaigns @@ -78,4 +86,23 @@ Brand style is stored as a JSON file with the following structure: ### Updating Brand Style 1. Use the API endpoint `PUT /brand-style` with the updated style guidelines -2. The system will automatically update the style file \ No newline at end of file +2. The system will automatically update the style file and create a backup + +### Managing User Queries + +1. User queries are automatically stored when using the generation API +2. Each query is stored with its parameters, generated content, and any feedback +3. Use the `GET /user-queries` endpoint to retrieve historical data with pagination + +### Vector Store Management + +The vector store is automatically maintained by the system: +1. New content is automatically embedded and added to the store +2. Similar content can be retrieved using the `POST /find-similar` endpoint +3. The store is periodically optimized for performance + +## Backup and Maintenance + +1. All JSON files are versioned and can be restored if needed +2. The SQLite database is automatically backed up daily +3. The vector store can be rebuilt from the source content if necessary diff --git a/docs/API_DOCUMENTATION.md b/docs/API_DOCUMENTATION.md index 7868a6e..3efffcd 100644 --- a/docs/API_DOCUMENTATION.md +++ b/docs/API_DOCUMENTATION.md @@ -4,7 +4,7 @@ ### Generate Copy -Generates marketing copy based on the provided prompt and optional parameters. +Generates marketing copy based on the provided prompt and parameters. **Endpoint**: `/generate-copy` **Method**: POST @@ -15,52 +15,55 @@ Generates marketing copy based on the provided prompt and optional parameters. { "prompt": "Write a social media post for our new product launch", "content_type": "social_media", + "tone": "professional", "length": "medium", "include_cta": true } ``` -**Parameters**: -- `prompt` (string, required): The main instruction for generating content -- `content_type` (string, optional): Type of content to generate (social_media, email, blog, website, etc.) -- `length` (string, optional): Content length (short, medium, long) -- `include_cta` (boolean, optional): Whether to include a call to action - **Response**: ```json { - "status": "success", - "content": "Exciting news! Our revolutionary new product has just landed...", - "suggestions": [ - "Alternative headline option 1", - "Alternative headline option 2" - ], + "content": "Generated marketing content", "metadata": { "content_type": "social_media", - "tone": "excited", - "word_count": 85, - "generated_at": "2025-04-17T10:30:45Z" + "timestamp": "2024-01-01T12:00:00Z", + "alignment_score": 0.95 } } ``` -### Get Brand Style Guidelines +### List User Queries -Retrieves the current brand style guidelines. +Retrieves historical user queries with pagination. -**Endpoint**: `/brand-style` -**Method**: GET +**Endpoint**: `/user-queries` +**Method**: GET +**Query Parameters**: +- `page` (optional, default: 1): Page number +- `limit` (optional, default: 10): Items per page +- `content_type` (optional): Filter by content type **Response**: ```json { - "brand_name": "Adriana James", - "tone": ["professional", "friendly", "inspiring"], - "voice_characteristics": ["clear", "direct", "empowering"], - "taboo_words": ["cheap", "discount", "bargain"], - "preferred_terms": { - "customers": "clients", - "products": "solutions" + "items": [ + { + "prompt": "Write a social media post...", + "parameters": { + "content_type": "social_media", + "tone": "professional", + "length": "medium", + "include_cta": true + }, + "timestamp": "2024-01-01T12:00:00Z" + } + ], + "pagination": { + "total": 45, + "page": 1, + "limit": 10, + "pages": 5 } } ``` @@ -76,9 +79,9 @@ Updates the brand style guidelines. **Request Body**: ```json { - "tone": ["professional", "friendly", "inspiring", "innovative"], + "tone": ["professional", "friendly", "inspiring"], "voice_characteristics": ["clear", "direct", "empowering"], - "taboo_words": ["cheap", "discount", "bargain", "basic"], + "taboo_words": ["cheap", "discount", "bargain"], "preferred_terms": { "customers": "clients", "products": "solutions", @@ -91,7 +94,8 @@ Updates the brand style guidelines. ```json { "status": "success", - "message": "Brand style updated successfully" + "message": "Brand style updated successfully", + "timestamp": "2024-01-01T12:00:00Z" } ``` @@ -107,9 +111,9 @@ Adds new marketing content for AI training. ```json { "content_type": "email_campaign", - "content": "Dear valued client, We're thrilled to announce...", + "content": "Dear valued client...", "metadata": { - "campaign_name": "Spring Launch 2025", + "campaign_name": "Spring Launch 2024", "performance_metrics": { "open_rate": 0.42, "click_rate": 0.15 @@ -123,37 +127,34 @@ Adds new marketing content for AI training. { "status": "success", "message": "Training data added successfully", - "data_id": "12345" + "data_id": "unique-identifier" } ``` ### List Training Data -Retrieves a list of available training data. +Retrieves available training data with pagination. **Endpoint**: `/training-data` -**Method**: GET - +**Method**: GET **Query Parameters**: +- `page` (optional, default: 1): Page number +- `limit` (optional, default: 10): Items per page - `content_type` (optional): Filter by content type -- `page` (optional): Page number for pagination -- `limit` (optional): Number of items per page **Response**: ```json { "items": [ { - "id": "12345", + "id": "unique-identifier", "content_type": "email_campaign", - "preview": "Dear valued client, We're thrilled to announce...", - "added_at": "2025-04-10T14:30:00Z" - }, - { - "id": "12346", - "content_type": "social_media", - "preview": "Exciting news! Our revolutionary new product...", - "added_at": "2025-04-11T09:15:00Z" + "preview": "Dear valued client...", + "added_at": "2024-01-01T12:00:00Z", + "performance_metrics": { + "open_rate": 0.42, + "click_rate": 0.15 + } } ], "pagination": { @@ -167,19 +168,20 @@ Retrieves a list of available training data. ## Error Handling -All endpoints return standard HTTP status codes: +All endpoints return appropriate HTTP status codes: -- `200 OK`: Request successful -- `400 Bad Request`: Invalid request parameters -- `401 Unauthorized`: Authentication failed -- `404 Not Found`: Resource not found -- `500 Internal Server Error`: Server-side error +- 200: Success +- 400: Bad Request (invalid parameters) +- 401: Unauthorized +- 404: Not Found +- 500: Internal Server Error + +Error responses include detailed messages: -Error response format: ```json { "status": "error", "message": "Detailed error message", - "error_code": "ERROR_CODE" + "code": "ERROR_CODE" } ```