michael/marketing-assistant-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated Documentation

Browse Source
This commit is contained in:
Michael Ikehi
2025-04-18 20:21:11 +01:00
parent 71ad7b4d26
commit 6d07556b85
3 changed files with 104 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+8 -3
View File
@@ -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 - **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 - **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 - **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 ## 📋 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 - **Frontend**: Vanilla HTML, CSS, and JavaScript
- **AI Models**: Cohere's generation and embedding models - **AI Models**: Cohere's generation and embedding models
- **Vector Database**: FAISS for efficient content similarity search - **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 ## 🚀 Getting Started
@@ -66,8 +72,7 @@ API_HOST=localhost
API_PORT=8000 API_PORT=8000
# Database Configuration # Database Configuration
VECTOR_DB_PATH=./data/vector_store DATABASE_URL=sqlite:///./data/training_data.db
HISTORY_DB_PATH=./data/history.db
# Brand Configuration # Brand Configuration
BRAND_NAME=Adriana James BRAND_NAME=Adriana James
data/README.md
+38 -11
View File
@@ -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 - **user_queries/**: Stores user queries and requests for analytics and model improvement
- **style_guidelines/**: Contains brand tone and voice guidelines - **style_guidelines/**: Contains brand tone and voice guidelines
- **vector_store/**: Generated vector database for content retrieval (created automatically) - **vector_store/**: Generated vector database for content retrieval (created automatically)
- **db/**: Contains SQLite database files for structured data storage
## File Formats ## File Formats
@@ -22,15 +23,16 @@ Past campaign files are stored as JSON with the following structure:
"metadata": { "metadata": {
"campaign_name": "Name of the campaign", "campaign_name": "Name of the campaign",
"performance_metrics": { "performance_metrics": {
"metric1": value, "open_rate": 0.42,
"metric2": value "click_rate": 0.15,
"conversion_rate": 0.08
}, },
"content_type": "Same as above", "content_type": "Same as above",
"added_at": "ISO timestamp", "added_at": "2024-01-01T12:00:00Z",
"training_data": true "training_data": true
}, },
"document_id": 0, "document_id": "unique-identifier",
"timestamp": "ISO timestamp" "timestamp": "2024-01-01T12:00:00Z"
} }
``` ```
@@ -44,10 +46,13 @@ User query files store information about requests made to the AI:
"parameters": { "parameters": {
"content_type": "Type of content requested", "content_type": "Type of content requested",
"tone": "Requested tone", "tone": "Requested tone",
"length": "Requested length", "length": "short|medium|long",
"include_cta": true|false "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"], "taboo_words": ["cheap", "discount", "bargain"],
"preferred_terms": { "preferred_terms": {
"customers": "clients", "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 ### Adding Past Campaigns
@@ -78,4 +86,23 @@ Brand style is stored as a JSON file with the following structure:
### Updating Brand Style ### Updating Brand Style
1. Use the API endpoint `PUT /brand-style` with the updated style guidelines 1. Use the API endpoint `PUT /brand-style` with the updated style guidelines
2. The system will automatically update the style 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
docs/API_DOCUMENTATION.md
+55 -53
View File
@@ -4,7 +4,7 @@
### Generate Copy ### 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` **Endpoint**: `/generate-copy`
**Method**: POST **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", "prompt": "Write a social media post for our new product launch",
"content_type": "social_media", "content_type": "social_media",
"tone": "professional",
"length": "medium", "length": "medium",
"include_cta": true "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**: **Response**:
```json ```json
{ {
"status": "success", "content": "Generated marketing content",
"content": "Exciting news! Our revolutionary new product has just landed...",
"suggestions": [
"Alternative headline option 1",
"Alternative headline option 2"
],
"metadata": { "metadata": {
"content_type": "social_media", "content_type": "social_media",
"tone": "excited", "timestamp": "2024-01-01T12:00:00Z",
"word_count": 85, "alignment_score": 0.95
"generated_at": "2025-04-17T10:30:45Z"
} }
} }
``` ```
### Get Brand Style Guidelines ### List User Queries
Retrieves the current brand style guidelines. Retrieves historical user queries with pagination.
**Endpoint**: `/brand-style` **Endpoint**: `/user-queries`
**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
**Response**: **Response**:
```json ```json
{ {
"brand_name": "Adriana James", "items": [
"tone": ["professional", "friendly", "inspiring"], {
"voice_characteristics": ["clear", "direct", "empowering"], "prompt": "Write a social media post...",
"taboo_words": ["cheap", "discount", "bargain"], "parameters": {
"preferred_terms": { "content_type": "social_media",
"customers": "clients", "tone": "professional",
"products": "solutions" "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**: **Request Body**:
```json ```json
{ {
"tone": ["professional", "friendly", "inspiring", "innovative"], "tone": ["professional", "friendly", "inspiring"],
"voice_characteristics": ["clear", "direct", "empowering"], "voice_characteristics": ["clear", "direct", "empowering"],
"taboo_words": ["cheap", "discount", "bargain", "basic"], "taboo_words": ["cheap", "discount", "bargain"],
"preferred_terms": { "preferred_terms": {
"customers": "clients", "customers": "clients",
"products": "solutions", "products": "solutions",
@@ -91,7 +94,8 @@ Updates the brand style guidelines.
```json ```json
{ {
"status": "success", "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 ```json
{ {
"content_type": "email_campaign", "content_type": "email_campaign",
"content": "Dear valued client, We're thrilled to announce...", "content": "Dear valued client...",
"metadata": { "metadata": {
"campaign_name": "Spring Launch 2025", "campaign_name": "Spring Launch 2024",
"performance_metrics": { "performance_metrics": {
"open_rate": 0.42, "open_rate": 0.42,
"click_rate": 0.15 "click_rate": 0.15
@@ -123,37 +127,34 @@ Adds new marketing content for AI training.
{ {
"status": "success", "status": "success",
"message": "Training data added successfully", "message": "Training data added successfully",
"data_id": "12345" "data_id": "unique-identifier"
} }
``` ```
### List Training Data ### List Training Data
Retrieves a list of available training data. Retrieves available training data with pagination.
**Endpoint**: `/training-data` **Endpoint**: `/training-data`
**Method**: GET **Method**: GET
**Query Parameters**: **Query Parameters**:
- `page` (optional, default: 1): Page number
- `limit` (optional, default: 10): Items per page
- `content_type` (optional): Filter by content type - `content_type` (optional): Filter by content type
- `page` (optional): Page number for pagination
- `limit` (optional): Number of items per page
**Response**: **Response**:
```json ```json
{ {
"items": [ "items": [
{ {
"id": "12345", "id": "unique-identifier",
"content_type": "email_campaign", "content_type": "email_campaign",
"preview": "Dear valued client, We're thrilled to announce...", "preview": "Dear valued client...",
"added_at": "2025-04-10T14:30:00Z" "added_at": "2024-01-01T12:00:00Z",
}, "performance_metrics": {
{ "open_rate": 0.42,
"id": "12346", "click_rate": 0.15
"content_type": "social_media", }
"preview": "Exciting news! Our revolutionary new product...",
"added_at": "2025-04-11T09:15:00Z"
} }
], ],
"pagination": { "pagination": {
@@ -167,19 +168,20 @@ Retrieves a list of available training data.
## Error Handling ## Error Handling
All endpoints return standard HTTP status codes: All endpoints return appropriate HTTP status codes:
- `200 OK`: Request successful - 200: Success
- `400 Bad Request`: Invalid request parameters - 400: Bad Request (invalid parameters)
- `401 Unauthorized`: Authentication failed - 401: Unauthorized
- `404 Not Found`: Resource not found - 404: Not Found
- `500 Internal Server Error`: Server-side error - 500: Internal Server Error
Error responses include detailed messages:
Error response format:
```json ```json
{ {
"status": "error", "status": "error",
"message": "Detailed error message", "message": "Detailed error message",
"error_code": "ERROR_CODE" "code": "ERROR_CODE"
} }
``` ```