Detailed Docs & Onboarding improvements
This commit is contained in:
ajaysi
20
docs/Makefile
Normal file
20
docs/Makefile
Normal file
@@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
127
docs/api/ai_writers.rst
Normal file
127
docs/api/ai_writers.rst
Normal file
@@ -0,0 +1,127 @@
|
||||
AI Writers
|
||||
=========
|
||||
|
||||
This section documents the AI writer modules that provide specialized content generation for different platforms.
|
||||
|
||||
LinkedIn Writer
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.ai_writers.linkedin_writer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
LinkedIn Post Generator
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.linkedin_writer.modules.post_generator
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
LinkedIn Article Generator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.linkedin_writer.modules.article_generator
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
LinkedIn Profile Optimizer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.linkedin_writer.modules.profile_optimizer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Twitter Writer
|
||||
------------
|
||||
|
||||
.. automodule:: lib.ai_writers.twitter_writers
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Tweet Generator
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.twitter_writers.tweet_generator
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Facebook Writer
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_facebook_writer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Facebook Ad Copy Generator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_facebook_writer.modules.ad_copy_generator
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Facebook Carousel Generator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_facebook_writer.modules.facebook_carousel
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
YouTube Writers
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.ai_writers.youtube_writers
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Story Writer
|
||||
----------
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_story_writer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Copywriter
|
||||
---------
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_copywriter
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Blog Writers
|
||||
----------
|
||||
|
||||
GitHub Blogs
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.github_blogs
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Scholar Blogs
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.scholar_blogs
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Speech to Blog
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.speech_to_blog
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
12
docs/api/analytics.rst
Normal file
12
docs/api/analytics.rst
Normal file
@@ -0,0 +1,12 @@
|
||||
Analytics
|
||||
=========
|
||||
|
||||
This section documents the analytics modules that provide content performance tracking and visualization.
|
||||
|
||||
Analytics Engine
|
||||
--------------
|
||||
|
||||
.. automodule:: lib.analytics
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
51
docs/api/core.rst
Normal file
51
docs/api/core.rst
Normal file
@@ -0,0 +1,51 @@
|
||||
Core API
|
||||
========
|
||||
|
||||
This section documents the core modules of the AI-Writer platform.
|
||||
|
||||
Main Application
|
||||
--------------
|
||||
|
||||
.. automodule:: alwrity
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
GPT Providers
|
||||
-----------
|
||||
|
||||
Text Generation
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_generation.gemini_pro_text
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_generation.mistral_chat_completion
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_generation.deepseek_text_gen
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Image Generation
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_to_image_generation.main_generate_image_from_prompt
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_to_image_generation.gen_gemini_images
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_to_image_generation.gen_dali3_images
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
22
docs/api/database.rst
Normal file
22
docs/api/database.rst
Normal file
@@ -0,0 +1,22 @@
|
||||
Database
|
||||
========
|
||||
|
||||
This section documents the database modules that handle content storage, retrieval, and vector search capabilities.
|
||||
|
||||
Database Models
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.database
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Vector Database
|
||||
-------------
|
||||
|
||||
The vector database provides semantic search capabilities for content retrieval.
|
||||
|
||||
.. automodule:: lib.workspace.alwrity_data.vectordb
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
83
docs/api/index.rst
Normal file
83
docs/api/index.rst
Normal file
@@ -0,0 +1,83 @@
|
||||
.. _api-reference:
|
||||
|
||||
API Reference
|
||||
============
|
||||
|
||||
This section provides detailed documentation for the AI-Writer API, including module references, class hierarchies, and function specifications.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: API Documentation:
|
||||
|
||||
core
|
||||
ai_writers
|
||||
database
|
||||
utils
|
||||
analytics
|
||||
web_crawlers
|
||||
|
||||
Core Modules
|
||||
-----------
|
||||
|
||||
.. automodule:: alwrity
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
AI Writers
|
||||
---------
|
||||
|
||||
The AI Writers modules provide specialized content generation for different platforms and content types.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
ai_writers/linkedin
|
||||
ai_writers/twitter
|
||||
ai_writers/blog
|
||||
ai_writers/email
|
||||
|
||||
Database
|
||||
-------
|
||||
|
||||
The database modules handle content storage, retrieval, and vector search capabilities.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
database/models
|
||||
database/vector_store
|
||||
database/relational_store
|
||||
|
||||
Utilities
|
||||
--------
|
||||
|
||||
Utility modules provide supporting functionality across the application.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
utils/api_key_manager
|
||||
utils/ui_setup
|
||||
utils/seo_tools
|
||||
|
||||
Analytics
|
||||
--------
|
||||
|
||||
Analytics modules provide content performance tracking and visualization.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
analytics/content_analyzer
|
||||
analytics/analytics_ui
|
||||
|
||||
Web Crawlers
|
||||
-----------
|
||||
|
||||
Web crawler modules provide research capabilities by extracting information from the web.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
web_crawlers/async_web_crawler
|
||||
78
docs/api/utils.rst
Normal file
78
docs/api/utils.rst
Normal file
@@ -0,0 +1,78 @@
|
||||
Utilities
|
||||
=========
|
||||
|
||||
This section documents the utility modules that provide supporting functionality across the application.
|
||||
|
||||
API Key Manager
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.utils.api_key_manager
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Website Analyzer
|
||||
--------------
|
||||
|
||||
.. automodule:: lib.utils.website_analyzer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
UI Components
|
||||
-----------
|
||||
|
||||
.. automodule:: lib.alwrity_ui
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
SEO Tools
|
||||
--------
|
||||
|
||||
.. automodule:: lib.ai_seo_tools
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Marketing Tools
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.ai_marketing_tools
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Blog Processing
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.blog_metadata
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.blog_postprocessing
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.blog_sections
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Content Planning
|
||||
--------------
|
||||
|
||||
.. automodule:: lib.content_planning_calender
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Personalization
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.personalization
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
28
docs/api/web_crawlers.rst
Normal file
28
docs/api/web_crawlers.rst
Normal file
@@ -0,0 +1,28 @@
|
||||
Web Crawlers
|
||||
============
|
||||
|
||||
This section documents the web crawler modules that provide research capabilities by extracting information from the web.
|
||||
|
||||
Web Researcher
|
||||
------------
|
||||
|
||||
.. automodule:: lib.ai_web_researcher
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Web Crawlers
|
||||
----------
|
||||
|
||||
.. automodule:: lib.web_crawlers
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Research Storage
|
||||
--------------
|
||||
|
||||
.. automodule:: lib.workspace.alwrity_web_research
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
449
docs/architecture/api_design.rst
Normal file
449
docs/architecture/api_design.rst
Normal file
@@ -0,0 +1,449 @@
|
||||
API Design
|
||||
=========
|
||||
|
||||
This document outlines the API design principles and specifications for the AI-Writer platform.
|
||||
|
||||
API Design Principles
|
||||
-------------------
|
||||
|
||||
The AI-Writer API follows these core design principles:
|
||||
|
||||
1. **RESTful Architecture**
|
||||
|
||||
* Resource-oriented design
|
||||
* Standard HTTP methods (GET, POST, PUT, DELETE)
|
||||
* Consistent URL structure
|
||||
* Stateless interactions
|
||||
|
||||
2. **Consistent Response Format**
|
||||
|
||||
* JSON as the primary data format
|
||||
* Standard error response structure
|
||||
* Pagination for list endpoints
|
||||
* Hypermedia links where appropriate
|
||||
|
||||
3. **Versioning**
|
||||
|
||||
* API versioning in URL path (e.g., `/api/v1/`)
|
||||
* Backward compatibility within major versions
|
||||
* Deprecation notices before removing features
|
||||
|
||||
4. **Security**
|
||||
|
||||
* Authentication via API keys or OAuth 2.0
|
||||
* Rate limiting to prevent abuse
|
||||
* Input validation to prevent injection attacks
|
||||
* HTTPS for all communications
|
||||
|
||||
5. **Documentation**
|
||||
|
||||
* OpenAPI/Swagger specification
|
||||
* Interactive documentation
|
||||
* Code examples for common operations
|
||||
* Changelog for API updates
|
||||
|
||||
API Endpoints
|
||||
-----------
|
||||
|
||||
Content Management
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Create content
|
||||
POST /api/v1/content
|
||||
|
||||
# Get content by ID
|
||||
GET /api/v1/content/{content_id}
|
||||
|
||||
# Update content
|
||||
PUT /api/v1/content/{content_id}
|
||||
|
||||
# Delete content
|
||||
DELETE /api/v1/content/{content_id}
|
||||
|
||||
# List content with filtering
|
||||
GET /api/v1/content?type={type}&limit={limit}&offset={offset}
|
||||
|
||||
# Get content versions
|
||||
GET /api/v1/content/{content_id}/versions
|
||||
|
||||
# Revert to specific version
|
||||
POST /api/v1/content/{content_id}/revert/{version_id}
|
||||
|
||||
AI Generation
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Generate content from keywords
|
||||
POST /api/v1/generate/content
|
||||
|
||||
# Generate blog post
|
||||
POST /api/v1/generate/blog
|
||||
|
||||
# Generate social media post
|
||||
POST /api/v1/generate/social
|
||||
|
||||
# Generate email
|
||||
POST /api/v1/generate/email
|
||||
|
||||
# Generate outline
|
||||
POST /api/v1/generate/outline
|
||||
|
||||
# Generate image for content
|
||||
POST /api/v1/generate/image
|
||||
|
||||
Web Research
|
||||
~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Perform web research
|
||||
POST /api/v1/research
|
||||
|
||||
# Get research results
|
||||
GET /api/v1/research/{research_id}
|
||||
|
||||
# Search previous research
|
||||
GET /api/v1/research/search?query={query}
|
||||
|
||||
SEO Tools
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Analyze content for SEO
|
||||
POST /api/v1/seo/analyze
|
||||
|
||||
# Generate meta description
|
||||
POST /api/v1/seo/meta-description
|
||||
|
||||
# Generate SEO-friendly title
|
||||
POST /api/v1/seo/title
|
||||
|
||||
# Generate structured data
|
||||
POST /api/v1/seo/structured-data
|
||||
|
||||
# Generate alt text for images
|
||||
POST /api/v1/seo/alt-text
|
||||
|
||||
User Management
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Create user
|
||||
POST /api/v1/users
|
||||
|
||||
# Get user profile
|
||||
GET /api/v1/users/{user_id}
|
||||
|
||||
# Update user profile
|
||||
PUT /api/v1/users/{user_id}
|
||||
|
||||
# Delete user
|
||||
DELETE /api/v1/users/{user_id}
|
||||
|
||||
# Get user settings
|
||||
GET /api/v1/users/{user_id}/settings
|
||||
|
||||
# Update user settings
|
||||
PUT /api/v1/users/{user_id}/settings
|
||||
|
||||
API Key Management
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Create API key
|
||||
POST /api/v1/api-keys
|
||||
|
||||
# List API keys
|
||||
GET /api/v1/api-keys
|
||||
|
||||
# Revoke API key
|
||||
DELETE /api/v1/api-keys/{key_id}
|
||||
|
||||
Analytics
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Get content analytics
|
||||
GET /api/v1/analytics/content/{content_id}
|
||||
|
||||
# Get user analytics
|
||||
GET /api/v1/analytics/user/{user_id}
|
||||
|
||||
# Get system analytics
|
||||
GET /api/v1/analytics/system
|
||||
|
||||
Request and Response Examples
|
||||
---------------------------
|
||||
|
||||
Create Content
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Request:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
POST /api/v1/content
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {api_key}
|
||||
|
||||
{
|
||||
"title": "How to Improve SEO with AI",
|
||||
"content_type": "blog",
|
||||
"content": "# How to Improve SEO with AI\n\nIn this article, we'll explore...",
|
||||
"metadata": {
|
||||
"keywords": ["SEO", "AI", "content marketing"],
|
||||
"category": "digital marketing",
|
||||
"language": "en"
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"id": "c123e4567-e89b-12d3-a456-426614174000",
|
||||
"title": "How to Improve SEO with AI",
|
||||
"content_type": "blog",
|
||||
"content": "# How to Improve SEO with AI\n\nIn this article, we'll explore...",
|
||||
"metadata": {
|
||||
"keywords": ["SEO", "AI", "content marketing"],
|
||||
"category": "digital marketing",
|
||||
"language": "en"
|
||||
},
|
||||
"created_at": "2023-01-01T12:00:00Z",
|
||||
"updated_at": "2023-01-01T12:00:00Z",
|
||||
"user_id": "u123e4567-e89b-12d3-a456-426614174000",
|
||||
"links": {
|
||||
"self": "/api/v1/content/c123e4567-e89b-12d3-a456-426614174000",
|
||||
"versions": "/api/v1/content/c123e4567-e89b-12d3-a456-426614174000/versions",
|
||||
"analytics": "/api/v1/analytics/content/c123e4567-e89b-12d3-a456-426614174000"
|
||||
}
|
||||
}
|
||||
|
||||
Generate Blog Post
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Request:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
POST /api/v1/generate/blog
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {api_key}
|
||||
|
||||
{
|
||||
"keywords": ["artificial intelligence", "content creation"],
|
||||
"title": "The Future of Content Creation with AI",
|
||||
"tone": "informative",
|
||||
"length": "medium",
|
||||
"include_research": true,
|
||||
"target_audience": "marketers"
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"id": "g123e4567-e89b-12d3-a456-426614174000",
|
||||
"title": "The Future of Content Creation with AI",
|
||||
"content": "# The Future of Content Creation with AI\n\nArtificial intelligence is revolutionizing...",
|
||||
"metadata": {
|
||||
"keywords": ["artificial intelligence", "content creation"],
|
||||
"tone": "informative",
|
||||
"length": "medium",
|
||||
"word_count": 1250,
|
||||
"research_sources": [
|
||||
{
|
||||
"title": "AI in Content Marketing Report 2023",
|
||||
"url": "https://example.com/report",
|
||||
"accessed_at": "2023-01-01T10:30:00Z"
|
||||
}
|
||||
]
|
||||
},
|
||||
"created_at": "2023-01-01T12:05:00Z",
|
||||
"links": {
|
||||
"save": "/api/v1/content",
|
||||
"regenerate": "/api/v1/generate/blog",
|
||||
"edit": "/api/v1/generate/edit"
|
||||
}
|
||||
}
|
||||
|
||||
Error Response
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
HTTP/1.1 400 Bad Request
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"error": {
|
||||
"code": "invalid_request",
|
||||
"message": "The request was invalid",
|
||||
"details": [
|
||||
{
|
||||
"field": "keywords",
|
||||
"issue": "required",
|
||||
"description": "The keywords field is required"
|
||||
}
|
||||
]
|
||||
},
|
||||
"request_id": "req_123456",
|
||||
"documentation_url": "https://docs.alwrity.com/api/errors#invalid_request"
|
||||
}
|
||||
|
||||
API Authentication
|
||||
----------------
|
||||
|
||||
The AI-Writer API supports the following authentication methods:
|
||||
|
||||
1. **API Key Authentication**
|
||||
|
||||
* Include the API key in the Authorization header:
|
||||
`Authorization: Bearer {api_key}`
|
||||
* API keys can be generated and managed through the API or web interface
|
||||
* Different permission levels can be assigned to API keys
|
||||
|
||||
2. **OAuth 2.0 (for multi-user deployments)**
|
||||
|
||||
* Standard OAuth 2.0 flow with authorization code
|
||||
* Supports scopes for fine-grained permissions
|
||||
* Refresh token rotation for enhanced security
|
||||
|
||||
Rate Limiting
|
||||
-----------
|
||||
|
||||
To ensure fair usage and system stability, the API implements rate limiting:
|
||||
|
||||
* Rate limits are based on the user's plan
|
||||
* Limits are applied per API key
|
||||
* Rate limit information is included in response headers:
|
||||
* `X-RateLimit-Limit`: Total requests allowed in the current period
|
||||
* `X-RateLimit-Remaining`: Requests remaining in the current period
|
||||
* `X-RateLimit-Reset`: Time when the rate limit resets (Unix timestamp)
|
||||
|
||||
When a rate limit is exceeded, the API returns a 429 Too Many Requests response.
|
||||
|
||||
Pagination
|
||||
---------
|
||||
|
||||
List endpoints support pagination with the following parameters:
|
||||
|
||||
* `limit`: Number of items per page (default: 20, max: 100)
|
||||
* `offset`: Number of items to skip (for offset-based pagination)
|
||||
* `cursor`: Cursor for the next page (for cursor-based pagination)
|
||||
|
||||
Response includes pagination metadata:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"total": 45,
|
||||
"limit": 20,
|
||||
"offset": 0,
|
||||
"next_cursor": "cursor_for_next_page",
|
||||
"has_more": true
|
||||
}
|
||||
}
|
||||
|
||||
Filtering and Sorting
|
||||
-------------------
|
||||
|
||||
List endpoints support filtering and sorting:
|
||||
|
||||
* Filtering: `?field=value&another_field=another_value`
|
||||
* Range filtering: `?created_at_gte=2023-01-01&created_at_lte=2023-01-31`
|
||||
* Sorting: `?sort=field` (ascending) or `?sort=-field` (descending)
|
||||
* Multiple sort fields: `?sort=-created_at,title`
|
||||
|
||||
Versioning Strategy
|
||||
-----------------
|
||||
|
||||
The API uses a versioning strategy to ensure backward compatibility:
|
||||
|
||||
1. **Major Versions**
|
||||
|
||||
* Included in the URL path: `/api/v1/`, `/api/v2/`, etc.
|
||||
* Major versions may introduce breaking changes
|
||||
* Previous major versions are supported for at least 12 months after a new version is released
|
||||
|
||||
2. **Minor Updates**
|
||||
|
||||
* Backward-compatible changes within a major version
|
||||
* New endpoints or parameters may be added
|
||||
* Existing functionality remains unchanged
|
||||
|
||||
3. **Deprecation Process**
|
||||
|
||||
* Features to be removed are marked as deprecated
|
||||
* Deprecation notices are included in response headers
|
||||
* Deprecated features are supported for at least 6 months before removal
|
||||
|
||||
API Changelog
|
||||
-----------
|
||||
|
||||
The API changelog is maintained to track changes:
|
||||
|
||||
* **v1.0.0 (2023-01-01)**
|
||||
|
||||
* Initial release with core content management features
|
||||
* Basic AI generation capabilities
|
||||
* User management and authentication
|
||||
|
||||
* **v1.1.0 (2023-03-15)**
|
||||
|
||||
* Added SEO analysis endpoints
|
||||
* Enhanced content generation with research integration
|
||||
* Improved error handling and validation
|
||||
|
||||
* **v1.2.0 (2023-06-30)**
|
||||
|
||||
* Added analytics endpoints
|
||||
* Introduced cursor-based pagination
|
||||
* Added support for content versioning
|
||||
|
||||
Future API Roadmap
|
||||
----------------
|
||||
|
||||
Planned API enhancements:
|
||||
|
||||
1. **Content Collaboration**
|
||||
|
||||
* Endpoints for collaborative editing
|
||||
* Comment and feedback functionality
|
||||
* Role-based access control
|
||||
|
||||
2. **Advanced Analytics**
|
||||
|
||||
* Predictive performance metrics
|
||||
* Competitive analysis
|
||||
* Content optimization recommendations
|
||||
|
||||
3. **Workflow Automation**
|
||||
|
||||
* Scheduled content generation
|
||||
* Approval workflows
|
||||
* Integration with publishing platforms
|
||||
|
||||
4. **Multi-modal Content**
|
||||
|
||||
* Enhanced image generation
|
||||
* Audio content generation
|
||||
* Video script generation
|
||||
170
docs/architecture/architecture_overview.rst
Normal file
170
docs/architecture/architecture_overview.rst
Normal file
@@ -0,0 +1,170 @@
|
||||
Architecture Overview
|
||||
====================
|
||||
|
||||
This document provides a comprehensive overview of the AI-Writer architecture, explaining the system's components, their interactions, and the design principles behind the implementation.
|
||||
|
||||
High-Level Architecture
|
||||
----------------------
|
||||
|
||||
.. image:: diagrams/high_level_architecture.png
|
||||
:alt: High-level architecture diagram of AI-Writer
|
||||
:width: 100%
|
||||
|
||||
The AI-Writer platform consists of several key components:
|
||||
|
||||
1. **User Interface Layer**
|
||||
|
||||
* Streamlit-based web interface
|
||||
* Command-line interface for automation
|
||||
* API endpoints for programmatic access
|
||||
|
||||
2. **Core Services Layer**
|
||||
|
||||
* AI Writers: Various specialized content generation modules
|
||||
* Web Research: Tools for gathering factual information from the internet
|
||||
* SEO Tools: Utilities for optimizing content for search engines
|
||||
* Analytics: Content performance tracking and analysis
|
||||
|
||||
3. **Data Storage Layer**
|
||||
|
||||
* Vector Database (ChromaDB): Stores embeddings for semantic search
|
||||
* Relational Database (SQLite): Stores structured data like user preferences and content metadata
|
||||
|
||||
4. **External Integrations Layer**
|
||||
|
||||
* LLM Providers: OpenAI, Google Gemini, Anthropic, etc.
|
||||
* Search Providers: Tavily, SerperDev, Exa, etc.
|
||||
* Image Generation: Stability AI
|
||||
* Publishing Platforms: WordPress, Jekyll, etc.
|
||||
|
||||
Database Architecture
|
||||
--------------------
|
||||
|
||||
.. image:: diagrams/database_architecture.png
|
||||
:alt: Database architecture diagram of AI-Writer
|
||||
:width: 100%
|
||||
|
||||
The database architecture consists of two main components:
|
||||
|
||||
1. **Vector Storage**
|
||||
|
||||
* Uses ChromaDB for storing and retrieving text embeddings
|
||||
* Enables semantic search capabilities
|
||||
* Stores content in collections for efficient retrieval
|
||||
|
||||
2. **Relational Storage**
|
||||
|
||||
* Uses SQLite for structured data storage
|
||||
* Key models include:
|
||||
- User: Stores user preferences and settings
|
||||
- ContentItem: Represents content created by users
|
||||
- ContentVersion: Tracks version history of content
|
||||
- Analytics: Stores performance metrics for content
|
||||
|
||||
Content Generation Workflow
|
||||
--------------------------
|
||||
|
||||
.. image:: diagrams/content_generation_workflow.png
|
||||
:alt: Content generation workflow diagram of AI-Writer
|
||||
:width: 100%
|
||||
|
||||
The content generation process follows these steps:
|
||||
|
||||
1. **Input Phase**
|
||||
|
||||
* User provides keywords, topics, or other input parameters
|
||||
* System configures the generation process based on user preferences
|
||||
|
||||
2. **Research Phase**
|
||||
|
||||
* Web research is conducted using various search providers
|
||||
* Relevant information is gathered and processed
|
||||
* Facts are extracted and organized for use in content generation
|
||||
|
||||
3. **Content Creation Phase**
|
||||
|
||||
* Content outline is generated based on research
|
||||
* Initial draft is created using AI models
|
||||
* Final content is refined and polished
|
||||
|
||||
4. **Enhancement Phase**
|
||||
|
||||
* SEO optimization is applied to improve search visibility
|
||||
* Images are generated or selected to complement the content
|
||||
* Metadata is generated for better categorization and discovery
|
||||
|
||||
5. **Storage Phase**
|
||||
|
||||
* Content is stored in both vector and relational databases
|
||||
* Embeddings are created for semantic search capabilities
|
||||
* Metadata is indexed for efficient retrieval
|
||||
|
||||
6. **Publishing Phase**
|
||||
|
||||
* Content is formatted for the target platform
|
||||
* Publishing options include WordPress, Markdown, and others
|
||||
* Content is delivered to the user or published directly
|
||||
|
||||
Design Principles
|
||||
----------------
|
||||
|
||||
The AI-Writer architecture is built on the following design principles:
|
||||
|
||||
1. **Modularity**
|
||||
|
||||
* Components are designed to be independent and interchangeable
|
||||
* New AI models and services can be added with minimal changes
|
||||
* Functionality is organized into logical modules
|
||||
|
||||
2. **Extensibility**
|
||||
|
||||
* The system is designed to be easily extended with new features
|
||||
* Plugin architecture allows for custom integrations
|
||||
* Configuration options enable customization without code changes
|
||||
|
||||
3. **Reliability**
|
||||
|
||||
* Error handling is implemented throughout the system
|
||||
* Fallback mechanisms ensure continued operation
|
||||
* Logging provides visibility into system behavior
|
||||
|
||||
4. **Performance**
|
||||
|
||||
* Caching is used to improve response times
|
||||
* Asynchronous processing for long-running tasks
|
||||
* Efficient data storage and retrieval mechanisms
|
||||
|
||||
5. **Security**
|
||||
|
||||
* API keys are securely stored and managed
|
||||
* User data is protected with appropriate measures
|
||||
* Input validation prevents common security issues
|
||||
|
||||
Future Architecture Enhancements
|
||||
-------------------------------
|
||||
|
||||
Planned improvements to the architecture include:
|
||||
|
||||
1. **Distributed Processing**
|
||||
|
||||
* Support for distributed content generation
|
||||
* Load balancing for improved scalability
|
||||
* Parallel processing of research and generation tasks
|
||||
|
||||
2. **Advanced Caching**
|
||||
|
||||
* Intelligent caching of common queries and results
|
||||
* Cache invalidation strategies for fresh content
|
||||
* Distributed cache for multi-user environments
|
||||
|
||||
3. **Enhanced Security**
|
||||
|
||||
* Role-based access control
|
||||
* End-to-end encryption for sensitive data
|
||||
* Advanced authentication mechanisms
|
||||
|
||||
4. **Containerization**
|
||||
|
||||
* Docker containers for easier deployment
|
||||
* Kubernetes support for orchestration
|
||||
* Microservices architecture for better scalability
|
||||
171
docs/architecture/component_diagram.rst
Normal file
171
docs/architecture/component_diagram.rst
Normal file
@@ -0,0 +1,171 @@
|
||||
Component Diagram
|
||||
================
|
||||
|
||||
This document provides detailed information about the components of the AI-Writer system and their interactions.
|
||||
|
||||
Core Components
|
||||
--------------
|
||||
|
||||
AI Writers
|
||||
~~~~~~~~~~
|
||||
|
||||
The AI Writers component is responsible for generating various types of content using AI models. It includes several specialized writers:
|
||||
|
||||
- **Blog Writer**: Generates blog posts based on keywords and web research
|
||||
- **News Article Writer**: Creates news articles with citations from current events
|
||||
- **Social Media Writer**: Produces content for various social platforms
|
||||
- **Email Writer**: Generates professional and business emails
|
||||
- **Story Writer**: Creates narrative content based on user input
|
||||
- **YouTube Script Writer**: Develops scripts for video content
|
||||
|
||||
Each writer implements a common interface but has specialized logic for its specific content type. The writers interact with LLM providers through a unified API layer that handles authentication, rate limiting, and error handling.
|
||||
|
||||
Web Research
|
||||
~~~~~~~~~~~
|
||||
|
||||
The Web Research component gathers information from the internet to provide factual context for content generation. It includes:
|
||||
|
||||
- **SERP Integration**: Retrieves search engine results
|
||||
- **Tavily Integration**: Uses AI-powered search for relevant information
|
||||
- **Exa Integration**: Performs semantic search for related content
|
||||
- **Web Crawler**: Extracts content from specified URLs
|
||||
- **Content Analyzer**: Processes and summarizes gathered information
|
||||
|
||||
This component ensures that generated content is factually accurate and up-to-date by providing relevant research data to the AI Writers.
|
||||
|
||||
SEO Tools
|
||||
~~~~~~~~~
|
||||
|
||||
The SEO Tools component provides utilities for optimizing content for search engines:
|
||||
|
||||
- **Keyword Analyzer**: Identifies and analyzes target keywords
|
||||
- **Meta Description Generator**: Creates SEO-friendly meta descriptions
|
||||
- **Title Generator**: Produces optimized titles for content
|
||||
- **Structured Data Generator**: Creates schema markup for rich snippets
|
||||
- **Image Optimizer**: Optimizes images for web performance
|
||||
- **On-Page SEO Analyzer**: Evaluates content for SEO best practices
|
||||
|
||||
These tools work together to ensure that generated content has the best chance of ranking well in search engines.
|
||||
|
||||
Analytics
|
||||
~~~~~~~~
|
||||
|
||||
The Analytics component tracks and analyzes content performance:
|
||||
|
||||
- **Content Metrics**: Measures readability, engagement potential, and other metrics
|
||||
- **Performance Tracker**: Monitors content performance over time
|
||||
- **Recommendation Engine**: Suggests improvements based on analytics
|
||||
- **Report Generator**: Creates reports on content effectiveness
|
||||
|
||||
This component helps users understand how their content is performing and how it can be improved.
|
||||
|
||||
Data Storage
|
||||
-----------
|
||||
|
||||
Vector Database
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The Vector Database component uses ChromaDB to store and retrieve text embeddings:
|
||||
|
||||
- **Embedding Generator**: Creates vector representations of text
|
||||
- **Collection Manager**: Organizes embeddings into collections
|
||||
- **Semantic Search**: Performs similarity searches on embeddings
|
||||
- **Metadata Manager**: Associates metadata with embeddings
|
||||
|
||||
This component enables semantic search capabilities, allowing users to find content based on meaning rather than just keywords.
|
||||
|
||||
Relational Database
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Relational Database component uses SQLite to store structured data:
|
||||
|
||||
- **User Manager**: Handles user data and preferences
|
||||
- **Content Repository**: Stores content items and metadata
|
||||
- **Version Control**: Tracks content versions and changes
|
||||
- **Analytics Storage**: Stores performance metrics and analytics data
|
||||
|
||||
This component provides persistent storage for all structured data in the system.
|
||||
|
||||
External Integrations
|
||||
--------------------
|
||||
|
||||
LLM Providers
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The LLM Providers component integrates with various AI models:
|
||||
|
||||
- **OpenAI Integration**: Connects to GPT models
|
||||
- **Google Gemini Integration**: Interfaces with Gemini models
|
||||
- **Anthropic Integration**: Works with Claude models
|
||||
- **Ollama Integration**: Supports local LLM deployment
|
||||
|
||||
This component provides a unified interface to different AI models, allowing the system to use the best model for each task.
|
||||
|
||||
Search Providers
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The Search Providers component connects to external search services:
|
||||
|
||||
- **Tavily Client**: Interfaces with Tavily AI search
|
||||
- **SerperDev Client**: Connects to SerperDev API
|
||||
- **Exa Client**: Integrates with Exa search API
|
||||
- **Google Search Client**: Provides access to Google search results
|
||||
|
||||
These integrations enable the system to gather relevant information from the internet for content generation.
|
||||
|
||||
Image Generation
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The Image Generation component creates images to complement content:
|
||||
|
||||
- **Stability AI Integration**: Connects to Stable Diffusion models
|
||||
- **DALL-E Integration**: Interfaces with OpenAI's DALL-E
|
||||
- **Image Processor**: Optimizes and formats generated images
|
||||
- **Image Repository**: Stores and manages generated images
|
||||
|
||||
This component enhances content with relevant visuals, improving engagement and comprehension.
|
||||
|
||||
Publishing Platforms
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Publishing Platforms component enables content distribution:
|
||||
|
||||
- **WordPress Integration**: Publishes content to WordPress sites
|
||||
- **Markdown Exporter**: Creates Markdown files for static sites
|
||||
- **HTML Exporter**: Generates HTML for web publishing
|
||||
- **API Connectors**: Interfaces with various content platforms
|
||||
|
||||
This component streamlines the process of publishing generated content to various platforms.
|
||||
|
||||
Component Interactions
|
||||
---------------------
|
||||
|
||||
Content Generation Flow
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. User provides input parameters through the UI
|
||||
2. Web Research gathers relevant information
|
||||
3. AI Writers generate content using research data and LLM providers
|
||||
4. SEO Tools optimize the content for search engines
|
||||
5. Content is stored in both Vector and Relational databases
|
||||
6. Analytics evaluates the content quality and potential performance
|
||||
7. Content is prepared for publishing through the Publishing Platforms
|
||||
|
||||
Data Flow
|
||||
~~~~~~~~~
|
||||
|
||||
1. User preferences and settings flow from UI to Relational Database
|
||||
2. Research data flows from Web Research to AI Writers
|
||||
3. Generated content flows from AI Writers to SEO Tools
|
||||
4. Optimized content flows to Data Storage components
|
||||
5. Content metrics flow from Analytics to Relational Database
|
||||
6. Published content flows from Publishing Platforms to external systems
|
||||
|
||||
Error Handling
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. LLM provider errors are handled by fallback mechanisms
|
||||
2. Web Research failures trigger alternative search methods
|
||||
3. Database errors are logged and retried with exponential backoff
|
||||
4. Publishing failures are queued for retry
|
||||
5. All errors are logged for monitoring and debugging
|
||||
306
docs/architecture/database_schema.rst
Normal file
306
docs/architecture/database_schema.rst
Normal file
@@ -0,0 +1,306 @@
|
||||
Database Schema
|
||||
==============
|
||||
|
||||
This document describes the database schema used in the AI-Writer platform, including both the relational database and vector database components.
|
||||
|
||||
Relational Database Schema
|
||||
------------------------
|
||||
|
||||
AI-Writer uses SQLAlchemy ORM to interact with the relational database. The schema consists of the following main tables:
|
||||
|
||||
User
|
||||
~~~~
|
||||
|
||||
Stores user information and preferences.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class User(Base):
|
||||
__tablename__ = "users"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
username = Column(String, unique=True, nullable=False)
|
||||
email = Column(String, unique=True, nullable=False)
|
||||
password_hash = Column(String, nullable=False)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
api_keys = relationship("ApiKey", back_populates="user")
|
||||
contents = relationship("Content", back_populates="user")
|
||||
settings = relationship("UserSetting", back_populates="user", uselist=False)
|
||||
|
||||
ApiKey
|
||||
~~~~~~
|
||||
|
||||
Stores encrypted API keys for various services.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class ApiKey(Base):
|
||||
__tablename__ = "api_keys"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"))
|
||||
service_name = Column(String, nullable=False)
|
||||
encrypted_key = Column(String, nullable=False)
|
||||
is_active = Column(Boolean, default=True)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
user = relationship("User", back_populates="api_keys")
|
||||
|
||||
Content
|
||||
~~~~~~~
|
||||
|
||||
Stores generated content with metadata.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class Content(Base):
|
||||
__tablename__ = "contents"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"))
|
||||
title = Column(String, nullable=False)
|
||||
content_type = Column(String, nullable=False) # blog, linkedin, twitter, etc.
|
||||
content_text = Column(Text, nullable=False)
|
||||
metadata = Column(JSON)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
user = relationship("User", back_populates="contents")
|
||||
versions = relationship("ContentVersion", back_populates="content")
|
||||
analytics = relationship("ContentAnalytics", back_populates="content")
|
||||
|
||||
ContentVersion
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Tracks versions of content for history and rollback.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class ContentVersion(Base):
|
||||
__tablename__ = "content_versions"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
content_id = Column(Integer, ForeignKey("contents.id"))
|
||||
version_number = Column(Integer, nullable=False)
|
||||
content_text = Column(Text, nullable=False)
|
||||
metadata = Column(JSON)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
content = relationship("Content", back_populates="versions")
|
||||
|
||||
ContentAnalytics
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Stores analytics data for content performance.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class ContentAnalytics(Base):
|
||||
__tablename__ = "content_analytics"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
content_id = Column(Integer, ForeignKey("contents.id"))
|
||||
views = Column(Integer, default=0)
|
||||
likes = Column(Integer, default=0)
|
||||
shares = Column(Integer, default=0)
|
||||
comments = Column(Integer, default=0)
|
||||
engagement_rate = Column(Float, default=0.0)
|
||||
last_updated = Column(DateTime, default=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
content = relationship("Content", back_populates="analytics")
|
||||
|
||||
UserSetting
|
||||
~~~~~~~~~~
|
||||
|
||||
Stores user preferences and settings.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class UserSetting(Base):
|
||||
__tablename__ = "user_settings"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"), unique=True)
|
||||
preferred_ai_provider = Column(String)
|
||||
default_content_type = Column(String)
|
||||
ui_theme = Column(String, default="light")
|
||||
language = Column(String, default="en")
|
||||
settings_json = Column(JSON)
|
||||
|
||||
# Relationships
|
||||
user = relationship("User", back_populates="settings")
|
||||
|
||||
Template
|
||||
~~~~~~~
|
||||
|
||||
Stores reusable content templates.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class Template(Base):
|
||||
__tablename__ = "templates"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"))
|
||||
name = Column(String, nullable=False)
|
||||
content_type = Column(String, nullable=False)
|
||||
template_text = Column(Text, nullable=False)
|
||||
variables = Column(JSON)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
user = relationship("User")
|
||||
|
||||
Vector Database Schema
|
||||
--------------------
|
||||
|
||||
AI-Writer uses ChromaDB for vector storage, which enables semantic search and retrieval of content. The vector database stores:
|
||||
|
||||
1. **Content Embeddings**
|
||||
|
||||
* Generated from content text using embedding models
|
||||
* Used for semantic search and content similarity
|
||||
|
||||
2. **Metadata**
|
||||
|
||||
* Content ID (linking to relational database)
|
||||
* Content type
|
||||
* Creation date
|
||||
* Keywords and tags
|
||||
|
||||
3. **Collections**
|
||||
|
||||
ChromaDB organizes embeddings into collections:
|
||||
|
||||
* `content_embeddings`: Main collection for all content
|
||||
* `user_{user_id}_content`: Per-user content collections
|
||||
* `{content_type}_embeddings`: Collections by content type
|
||||
|
||||
Vector Database Operations
|
||||
------------------------
|
||||
|
||||
The vector database supports the following operations:
|
||||
|
||||
1. **Adding Content**
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def add_content_to_vector_db(content_id, content_text, metadata):
|
||||
"""Add content to the vector database.
|
||||
|
||||
Args:
|
||||
content_id: The ID of the content in the relational database.
|
||||
content_text: The text content to embed.
|
||||
metadata: Additional metadata for the content.
|
||||
"""
|
||||
embeddings = get_embeddings(content_text)
|
||||
collection = get_collection("content_embeddings")
|
||||
collection.add(
|
||||
ids=[str(content_id)],
|
||||
embeddings=[embeddings],
|
||||
metadatas=[metadata],
|
||||
documents=[content_text]
|
||||
)
|
||||
|
||||
2. **Searching Content**
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def search_similar_content(query_text, limit=5):
|
||||
"""Search for similar content using vector similarity.
|
||||
|
||||
Args:
|
||||
query_text: The query text to search for.
|
||||
limit: Maximum number of results to return.
|
||||
|
||||
Returns:
|
||||
List of similar content items with their similarity scores.
|
||||
"""
|
||||
query_embedding = get_embeddings(query_text)
|
||||
collection = get_collection("content_embeddings")
|
||||
results = collection.query(
|
||||
query_embeddings=[query_embedding],
|
||||
n_results=limit
|
||||
)
|
||||
return results
|
||||
|
||||
3. **Updating Content**
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def update_content_in_vector_db(content_id, new_content_text, metadata):
|
||||
"""Update content in the vector database.
|
||||
|
||||
Args:
|
||||
content_id: The ID of the content to update.
|
||||
new_content_text: The updated text content.
|
||||
metadata: Updated metadata.
|
||||
"""
|
||||
new_embedding = get_embeddings(new_content_text)
|
||||
collection = get_collection("content_embeddings")
|
||||
collection.update(
|
||||
ids=[str(content_id)],
|
||||
embeddings=[new_embedding],
|
||||
metadatas=[metadata],
|
||||
documents=[new_content_text]
|
||||
)
|
||||
|
||||
Database Migrations
|
||||
-----------------
|
||||
|
||||
AI-Writer uses Alembic for database migrations. The migration workflow is:
|
||||
|
||||
1. **Create Migration**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
alembic revision --autogenerate -m "Description of changes"
|
||||
|
||||
2. **Apply Migration**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
alembic upgrade head
|
||||
|
||||
3. **Rollback Migration**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
alembic downgrade -1
|
||||
|
||||
Database Backup and Restore
|
||||
-------------------------
|
||||
|
||||
Regular database backups are recommended:
|
||||
|
||||
1. **SQLite Backup**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Backup
|
||||
sqlite3 data/alwrity.db .dump > backup.sql
|
||||
|
||||
# Restore
|
||||
sqlite3 data/alwrity.db < backup.sql
|
||||
|
||||
2. **Vector Database Backup**
|
||||
|
||||
ChromaDB data is stored in the specified directory and can be backed up by copying the directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Backup
|
||||
cp -r data/vectordb data/vectordb_backup
|
||||
|
||||
# Restore
|
||||
rm -rf data/vectordb
|
||||
cp -r data/vectordb_backup data/vectordb
|
||||
571
docs/architecture/deployment.rst
Normal file
571
docs/architecture/deployment.rst
Normal file
@@ -0,0 +1,571 @@
|
||||
Deployment Architecture
|
||||
=====================
|
||||
|
||||
This document outlines the deployment architecture for the AI-Writer platform, including deployment models, infrastructure requirements, and operational considerations.
|
||||
|
||||
Deployment Models
|
||||
---------------
|
||||
|
||||
AI-Writer supports multiple deployment models to accommodate different user needs and scale requirements:
|
||||
|
||||
Single-User Deployment
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Ideal for individual content creators or small teams:
|
||||
|
||||
1. **Local Installation**
|
||||
|
||||
* Runs on a single machine
|
||||
* SQLite database for data storage
|
||||
* Local file system for content storage
|
||||
* Minimal resource requirements
|
||||
|
||||
2. **Configuration**
|
||||
|
||||
* Simple configuration file
|
||||
* Environment variables for API keys
|
||||
* Local storage paths
|
||||
* Logging configuration
|
||||
|
||||
3. **Resource Requirements**
|
||||
|
||||
* CPU: 2+ cores
|
||||
* RAM: 4GB minimum (8GB recommended)
|
||||
* Storage: 10GB minimum
|
||||
* Python 3.9+ runtime
|
||||
|
||||
Multi-User Deployment
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Suitable for teams and organizations:
|
||||
|
||||
1. **Server Deployment**
|
||||
|
||||
* Dedicated server or cloud instance
|
||||
* PostgreSQL database
|
||||
* Shared file storage
|
||||
* Web server (Nginx/Apache) with WSGI/ASGI
|
||||
|
||||
2. **Docker Deployment**
|
||||
|
||||
* Containerized application
|
||||
* Docker Compose for orchestration
|
||||
* Persistent volumes for data
|
||||
* Separate containers for services
|
||||
|
||||
3. **Resource Requirements**
|
||||
|
||||
* CPU: 4+ cores
|
||||
* RAM: 16GB minimum
|
||||
* Storage: 50GB+ SSD
|
||||
* Network: 100Mbps+ bandwidth
|
||||
|
||||
Enterprise Deployment
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For large organizations with high volume requirements:
|
||||
|
||||
1. **Kubernetes Deployment**
|
||||
|
||||
* Containerized microservices
|
||||
* Horizontal scaling
|
||||
* Load balancing
|
||||
* High availability configuration
|
||||
|
||||
2. **Database Scaling**
|
||||
|
||||
* Database clustering
|
||||
* Read replicas
|
||||
* Connection pooling
|
||||
* Automated backups
|
||||
|
||||
3. **Resource Requirements**
|
||||
|
||||
* CPU: 8+ cores per node
|
||||
* RAM: 32GB+ per node
|
||||
* Storage: 100GB+ SSD with high IOPS
|
||||
* Network: 1Gbps+ bandwidth
|
||||
|
||||
Infrastructure Components
|
||||
-----------------------
|
||||
|
||||
Core Components
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **Application Servers**
|
||||
|
||||
* Runs the AI-Writer application code
|
||||
* Handles HTTP requests
|
||||
* Processes content generation tasks
|
||||
* Manages user sessions
|
||||
|
||||
2. **Database Servers**
|
||||
|
||||
* Stores relational data (SQLite/PostgreSQL)
|
||||
* Stores vector embeddings (ChromaDB)
|
||||
* Handles data persistence
|
||||
* Manages transactions and concurrency
|
||||
|
||||
3. **File Storage**
|
||||
|
||||
* Stores generated content
|
||||
* Stores uploaded files
|
||||
* Manages file versioning
|
||||
* Handles file access control
|
||||
|
||||
4. **Web Servers**
|
||||
|
||||
* Handles HTTP/HTTPS traffic
|
||||
* SSL termination
|
||||
* Static file serving
|
||||
* Request routing
|
||||
|
||||
Optional Components
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Cache Servers**
|
||||
|
||||
* Redis for caching
|
||||
* Session storage
|
||||
* Rate limiting
|
||||
* Task queuing
|
||||
|
||||
2. **Background Workers**
|
||||
|
||||
* Processes asynchronous tasks
|
||||
* Handles long-running operations
|
||||
* Manages scheduled jobs
|
||||
* Processes content generation queue
|
||||
|
||||
3. **Load Balancers**
|
||||
|
||||
* Distributes traffic across servers
|
||||
* Health checking
|
||||
* SSL termination
|
||||
* DDoS protection
|
||||
|
||||
4. **Monitoring Services**
|
||||
|
||||
* Application performance monitoring
|
||||
* Log aggregation
|
||||
* Metrics collection
|
||||
* Alerting
|
||||
|
||||
Deployment Topologies
|
||||
-------------------
|
||||
|
||||
Basic Topology
|
||||
~~~~~~~~~~~~
|
||||
|
||||
For single-user or small team deployments:
|
||||
|
||||
```
|
||||
[User] → [Web Server] → [AI-Writer Application] → [SQLite/PostgreSQL]
|
||||
→ [File Storage]
|
||||
→ [External APIs]
|
||||
```
|
||||
|
||||
Standard Topology
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
For multi-user deployments:
|
||||
|
||||
```
|
||||
[Users] → [Load Balancer] → [Web Servers] → [Application Servers] → [PostgreSQL Cluster]
|
||||
→ [Background Workers] → [File Storage]
|
||||
→ [Redis Cache]
|
||||
→ [External APIs]
|
||||
```
|
||||
|
||||
High-Availability Topology
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For enterprise deployments:
|
||||
|
||||
```
|
||||
[Users] → [CDN] → [Load Balancer] → [Web Servers (Multiple AZs)]
|
||||
→ [Application Servers (Multiple AZs)]
|
||||
→ [Background Workers (Multiple AZs)]
|
||||
→ [PostgreSQL (Primary + Replicas)]
|
||||
→ [Redis Cluster]
|
||||
→ [Distributed File Storage]
|
||||
→ [External APIs with Fallbacks]
|
||||
```
|
||||
|
||||
Deployment Process
|
||||
----------------
|
||||
|
||||
Installation Methods
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Manual Installation**
|
||||
|
||||
* Clone repository
|
||||
* Install dependencies
|
||||
* Configure environment
|
||||
* Initialize database
|
||||
* Start application
|
||||
|
||||
2. **Docker Installation**
|
||||
|
||||
* Pull Docker images
|
||||
* Configure Docker Compose
|
||||
* Start containers
|
||||
* Initialize services
|
||||
* Configure networking
|
||||
|
||||
3. **Kubernetes Installation**
|
||||
|
||||
* Apply Kubernetes manifests
|
||||
* Configure Helm charts
|
||||
* Set up persistent volumes
|
||||
* Configure ingress
|
||||
* Deploy services
|
||||
|
||||
Configuration Management
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Environment Variables**
|
||||
|
||||
* API keys and credentials
|
||||
* Database connection strings
|
||||
* Service endpoints
|
||||
* Feature flags
|
||||
|
||||
2. **Configuration Files**
|
||||
|
||||
* Application settings
|
||||
* Logging configuration
|
||||
* Database settings
|
||||
* Cache settings
|
||||
|
||||
3. **Secrets Management**
|
||||
|
||||
* Kubernetes secrets
|
||||
* Docker secrets
|
||||
* Vault integration
|
||||
* Encrypted configuration
|
||||
|
||||
Continuous Integration/Deployment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **CI Pipeline**
|
||||
|
||||
* Automated testing
|
||||
* Code quality checks
|
||||
* Security scanning
|
||||
* Build artifacts
|
||||
|
||||
2. **CD Pipeline**
|
||||
|
||||
* Automated deployment
|
||||
* Blue/green deployment
|
||||
* Canary releases
|
||||
* Rollback capability
|
||||
|
||||
3. **Infrastructure as Code**
|
||||
|
||||
* Terraform for infrastructure
|
||||
* Ansible for configuration
|
||||
* Helm charts for Kubernetes
|
||||
* Docker Compose for local deployment
|
||||
|
||||
Operational Considerations
|
||||
------------------------
|
||||
|
||||
Monitoring and Logging
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Application Monitoring**
|
||||
|
||||
* Performance metrics
|
||||
* Error tracking
|
||||
* User activity
|
||||
* API usage
|
||||
|
||||
2. **Infrastructure Monitoring**
|
||||
|
||||
* Resource utilization
|
||||
* Network traffic
|
||||
* Database performance
|
||||
* Storage capacity
|
||||
|
||||
3. **Logging Strategy**
|
||||
|
||||
* Centralized log collection
|
||||
* Structured logging
|
||||
* Log retention policy
|
||||
* Log analysis tools
|
||||
|
||||
Backup and Recovery
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Database Backups**
|
||||
|
||||
* Regular automated backups
|
||||
* Point-in-time recovery
|
||||
* Backup verification
|
||||
* Off-site backup storage
|
||||
|
||||
2. **File Storage Backups**
|
||||
|
||||
* Incremental backups
|
||||
* Version history
|
||||
* Disaster recovery
|
||||
* Backup encryption
|
||||
|
||||
3. **Recovery Procedures**
|
||||
|
||||
* Database restoration
|
||||
* File recovery
|
||||
* System rebuild
|
||||
* Disaster recovery testing
|
||||
|
||||
Scaling Strategies
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Vertical Scaling**
|
||||
|
||||
* Increase resources for existing servers
|
||||
* Upgrade database instances
|
||||
* Enhance storage performance
|
||||
* Optimize application code
|
||||
|
||||
2. **Horizontal Scaling**
|
||||
|
||||
* Add application servers
|
||||
* Database read replicas
|
||||
* Distributed caching
|
||||
* Load balancing
|
||||
|
||||
3. **Auto-scaling**
|
||||
|
||||
* Scale based on CPU/memory usage
|
||||
* Scale based on request volume
|
||||
* Scheduled scaling for predictable loads
|
||||
* Scale to zero for development environments
|
||||
|
||||
Security Considerations
|
||||
--------------------
|
||||
|
||||
Network Security
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **Firewall Configuration**
|
||||
|
||||
* Restrict access to necessary ports
|
||||
* Implement network segmentation
|
||||
* Configure security groups
|
||||
* DDoS protection
|
||||
|
||||
2. **TLS Configuration**
|
||||
|
||||
* TLS 1.3 support
|
||||
* Strong cipher suites
|
||||
* Certificate management
|
||||
* HSTS implementation
|
||||
|
||||
3. **VPN Access**
|
||||
|
||||
* Secure administrative access
|
||||
* Multi-factor authentication
|
||||
* Access logging
|
||||
* Role-based access control
|
||||
|
||||
Data Security
|
||||
~~~~~~~~~~
|
||||
|
||||
1. **Data Encryption**
|
||||
|
||||
* Encryption in transit
|
||||
* Encryption at rest
|
||||
* Key management
|
||||
* Regular key rotation
|
||||
|
||||
2. **Access Controls**
|
||||
|
||||
* Principle of least privilege
|
||||
* Role-based access
|
||||
* Regular access reviews
|
||||
* Privileged access management
|
||||
|
||||
3. **Compliance**
|
||||
|
||||
* Data residency requirements
|
||||
* Regulatory compliance
|
||||
* Privacy regulations
|
||||
* Security certifications
|
||||
|
||||
Deployment Checklist
|
||||
------------------
|
||||
|
||||
Pre-Deployment
|
||||
~~~~~~~~~~~~
|
||||
|
||||
1. **Environment Preparation**
|
||||
|
||||
* Verify infrastructure requirements
|
||||
* Configure networking
|
||||
* Set up security controls
|
||||
* Prepare databases
|
||||
|
||||
2. **Application Preparation**
|
||||
|
||||
* Verify application version
|
||||
* Check dependencies
|
||||
* Prepare configuration
|
||||
* Test in staging environment
|
||||
|
||||
3. **Documentation**
|
||||
|
||||
* Update deployment documentation
|
||||
* Prepare rollback procedures
|
||||
* Document configuration changes
|
||||
* Update user documentation
|
||||
|
||||
Deployment
|
||||
~~~~~~~~~
|
||||
|
||||
1. **Backup**
|
||||
|
||||
* Backup existing data
|
||||
* Backup configuration
|
||||
* Verify backup integrity
|
||||
* Prepare rollback point
|
||||
|
||||
2. **Deployment Steps**
|
||||
|
||||
* Follow deployment procedure
|
||||
* Monitor deployment progress
|
||||
* Verify service health
|
||||
* Run smoke tests
|
||||
|
||||
3. **Verification**
|
||||
|
||||
* Verify functionality
|
||||
* Check performance
|
||||
* Validate security
|
||||
* Test integrations
|
||||
|
||||
Post-Deployment
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **Monitoring**
|
||||
|
||||
* Monitor application performance
|
||||
* Watch for errors
|
||||
* Track user activity
|
||||
* Monitor resource usage
|
||||
|
||||
2. **Communication**
|
||||
|
||||
* Notify users of deployment
|
||||
* Provide release notes
|
||||
* Address initial feedback
|
||||
* Support user questions
|
||||
|
||||
3. **Optimization**
|
||||
|
||||
* Identify performance bottlenecks
|
||||
* Optimize resource usage
|
||||
* Fine-tune configuration
|
||||
* Plan for future improvements
|
||||
|
||||
Deployment Environments
|
||||
---------------------
|
||||
|
||||
Development Environment
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Purpose**
|
||||
|
||||
* Feature development
|
||||
* Bug fixing
|
||||
* Testing
|
||||
* Integration
|
||||
|
||||
2. **Characteristics**
|
||||
|
||||
* Minimal resources
|
||||
* Frequent updates
|
||||
* Non-production data
|
||||
* Developer access
|
||||
|
||||
3. **Configuration**
|
||||
|
||||
* Debug mode enabled
|
||||
* Verbose logging
|
||||
* Test API keys
|
||||
* Local development tools
|
||||
|
||||
Staging Environment
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Purpose**
|
||||
|
||||
* Pre-production testing
|
||||
* Performance testing
|
||||
* User acceptance testing
|
||||
* Deployment validation
|
||||
|
||||
2. **Characteristics**
|
||||
|
||||
* Similar to production
|
||||
* Controlled access
|
||||
* Sanitized production data
|
||||
* Regular refreshes
|
||||
|
||||
3. **Configuration**
|
||||
|
||||
* Production-like settings
|
||||
* Monitoring enabled
|
||||
* Test integrations
|
||||
* Staging API endpoints
|
||||
|
||||
Production Environment
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Purpose**
|
||||
|
||||
* Live user access
|
||||
* Business operations
|
||||
* Customer data
|
||||
* Revenue generation
|
||||
|
||||
2. **Characteristics**
|
||||
|
||||
* High availability
|
||||
* Scalability
|
||||
* Security
|
||||
* Performance
|
||||
|
||||
3. **Configuration**
|
||||
|
||||
* Optimized settings
|
||||
* Minimal logging
|
||||
* Production API keys
|
||||
* Strict access controls
|
||||
|
||||
Future Deployment Enhancements
|
||||
----------------------------
|
||||
|
||||
1. **Containerization Improvements**
|
||||
|
||||
* Optimize container images
|
||||
* Implement container security scanning
|
||||
* Enhance orchestration
|
||||
* Improve container networking
|
||||
|
||||
2. **Infrastructure as Code**
|
||||
|
||||
* Complete IaC implementation
|
||||
* Automated environment provisioning
|
||||
* Configuration management
|
||||
* Compliance as code
|
||||
|
||||
3. **Advanced Deployment Strategies**
|
||||
|
||||
* Feature flags
|
||||
* A/B testing infrastructure
|
||||
* Canary deployments
|
||||
* Progressive delivery
|
||||
BIN
docs/architecture/diagrams/content_generation_workflow.png
Normal file
BIN
docs/architecture/diagrams/content_generation_workflow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 142 KiB |
BIN
docs/architecture/diagrams/database_architecture.png
Normal file
BIN
docs/architecture/diagrams/database_architecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 91 KiB |
BIN
docs/architecture/diagrams/high_level_architecture.png
Normal file
BIN
docs/architecture/diagrams/high_level_architecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 158 KiB |
156
docs/architecture/index.rst
Normal file
156
docs/architecture/index.rst
Normal file
@@ -0,0 +1,156 @@
|
||||
System Architecture
|
||||
==================
|
||||
|
||||
This section provides a comprehensive overview of the AI-Writer system architecture, including component interactions, data flow, and design patterns.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Architecture Documentation:
|
||||
|
||||
overview
|
||||
components
|
||||
database_schema
|
||||
api_design
|
||||
security
|
||||
|
||||
Architecture Overview
|
||||
-------------------
|
||||
|
||||
.. include:: overview.rst
|
||||
|
||||
Component Diagram
|
||||
---------------
|
||||
|
||||
.. image:: diagrams/high_level_architecture.png
|
||||
:alt: AI-Writer High-Level Architecture Diagram
|
||||
:width: 800px
|
||||
|
||||
.. image:: diagrams/database_architecture.png
|
||||
:alt: AI-Writer Database Architecture Diagram
|
||||
:width: 800px
|
||||
|
||||
.. image:: diagrams/content_generation_workflow.png
|
||||
:alt: AI-Writer Content Generation Workflow Diagram
|
||||
:width: 800px
|
||||
|
||||
Key Components
|
||||
------------
|
||||
|
||||
The AI-Writer platform consists of several key components:
|
||||
|
||||
1. **User Interface Layer**
|
||||
|
||||
* Streamlit-based web interface
|
||||
* Component-based UI architecture
|
||||
* Responsive design for multiple devices
|
||||
|
||||
2. **Application Layer**
|
||||
|
||||
* Content generation modules
|
||||
* AI provider integrations
|
||||
* Research and analysis tools
|
||||
* Analytics and reporting
|
||||
|
||||
3. **Data Layer**
|
||||
|
||||
* Relational database (SQLite/PostgreSQL)
|
||||
* Vector database (ChromaDB)
|
||||
* File storage for generated content
|
||||
|
||||
4. **Integration Layer**
|
||||
|
||||
* API endpoints for external integration
|
||||
* Authentication and authorization
|
||||
* Rate limiting and caching
|
||||
|
||||
Component Interactions
|
||||
--------------------
|
||||
|
||||
The components interact through well-defined interfaces:
|
||||
|
||||
1. **UI to Application Layer**
|
||||
|
||||
* Event-driven interaction
|
||||
* State management through Streamlit session state
|
||||
* Asynchronous processing for long-running tasks
|
||||
|
||||
2. **Application to Data Layer**
|
||||
|
||||
* Repository pattern for data access
|
||||
* Transaction management
|
||||
* Connection pooling
|
||||
|
||||
3. **Application to External Services**
|
||||
|
||||
* API client abstractions
|
||||
* Retry mechanisms
|
||||
* Circuit breakers for fault tolerance
|
||||
|
||||
Data Flow
|
||||
--------
|
||||
|
||||
The typical data flow in the system:
|
||||
|
||||
1. User submits content generation request through UI
|
||||
2. Application layer validates and processes the request
|
||||
3. AI provider is called to generate content
|
||||
4. Generated content is stored in the database
|
||||
5. Content is returned to the UI for display and editing
|
||||
6. Analytics data is collected and stored
|
||||
|
||||
Deployment Architecture
|
||||
---------------------
|
||||
|
||||
AI-Writer supports multiple deployment models:
|
||||
|
||||
1. **Single-User Deployment**
|
||||
|
||||
* Local installation
|
||||
* SQLite database
|
||||
* Local file storage
|
||||
|
||||
2. **Multi-User Deployment**
|
||||
|
||||
* Docker-based deployment
|
||||
* PostgreSQL database
|
||||
* Shared file storage
|
||||
* Load balancing
|
||||
|
||||
3. **Cloud Deployment**
|
||||
|
||||
* Kubernetes orchestration
|
||||
* Cloud database services
|
||||
* Object storage
|
||||
* Auto-scaling
|
||||
|
||||
Technology Stack
|
||||
--------------
|
||||
|
||||
The AI-Writer platform is built on the following technologies:
|
||||
|
||||
1. **Frontend**
|
||||
|
||||
* Streamlit
|
||||
* HTML/CSS/JavaScript
|
||||
* Plotly for visualizations
|
||||
|
||||
2. **Backend**
|
||||
|
||||
* Python 3.9+
|
||||
* FastAPI for API endpoints
|
||||
* SQLAlchemy for ORM
|
||||
* ChromaDB for vector storage
|
||||
|
||||
3. **AI and ML**
|
||||
|
||||
* OpenAI GPT models
|
||||
* Google Gemini
|
||||
* Hugging Face transformers
|
||||
* Sentence transformers for embeddings
|
||||
|
||||
4. **Infrastructure**
|
||||
|
||||
* Docker
|
||||
* Docker Compose
|
||||
* Kubernetes (for cloud deployment)
|
||||
* GitHub Actions for CI/CD
|
||||
335
docs/architecture/security.rst
Normal file
335
docs/architecture/security.rst
Normal file
@@ -0,0 +1,335 @@
|
||||
Security Architecture
|
||||
===================
|
||||
|
||||
This document outlines the security architecture of the AI-Writer platform, including authentication, authorization, data protection, and security best practices.
|
||||
|
||||
Authentication and Authorization
|
||||
------------------------------
|
||||
|
||||
User Authentication
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
AI-Writer implements a multi-layered authentication system:
|
||||
|
||||
1. **Password-based Authentication**
|
||||
|
||||
* Passwords are hashed using bcrypt with appropriate work factors
|
||||
* Password complexity requirements are enforced
|
||||
* Account lockout after multiple failed attempts
|
||||
* Password reset via secure email workflow
|
||||
|
||||
2. **API Key Authentication**
|
||||
|
||||
* Unique API keys for programmatic access
|
||||
* Keys are stored using secure hashing
|
||||
* Keys can be scoped to specific permissions
|
||||
* Keys can be revoked at any time
|
||||
|
||||
3. **OAuth 2.0 (for multi-user deployments)**
|
||||
|
||||
* Standard OAuth 2.0 flow with authorization code
|
||||
* JWT tokens with appropriate expiration
|
||||
* Refresh token rotation
|
||||
* PKCE for public clients
|
||||
|
||||
Authorization Model
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
The platform uses a role-based access control (RBAC) system:
|
||||
|
||||
1. **User Roles**
|
||||
|
||||
* **Admin**: Full system access
|
||||
* **Editor**: Content creation and editing
|
||||
* **Viewer**: Read-only access to content
|
||||
* **API**: Programmatic access with limited scope
|
||||
|
||||
2. **Permission Scopes**
|
||||
|
||||
* `content:read`: View content
|
||||
* `content:write`: Create and edit content
|
||||
* `content:delete`: Delete content
|
||||
* `user:read`: View user information
|
||||
* `user:write`: Modify user information
|
||||
* `settings:read`: View settings
|
||||
* `settings:write`: Modify settings
|
||||
* `api:manage`: Manage API keys
|
||||
|
||||
3. **Resource-level Permissions**
|
||||
|
||||
* Permissions are checked at the resource level
|
||||
* Users can only access their own content
|
||||
* Sharing functionality with explicit permissions
|
||||
|
||||
Data Protection
|
||||
-------------
|
||||
|
||||
Encryption
|
||||
~~~~~~~~~
|
||||
|
||||
1. **Data in Transit**
|
||||
|
||||
* TLS 1.3 for all communications
|
||||
* Strong cipher suites
|
||||
* HSTS implementation
|
||||
* Certificate pinning for API clients
|
||||
|
||||
2. **Data at Rest**
|
||||
|
||||
* Database encryption
|
||||
* Encrypted file storage
|
||||
* Secure key management
|
||||
* Regular key rotation
|
||||
|
||||
3. **Sensitive Data**
|
||||
|
||||
* API keys and credentials are encrypted
|
||||
* PII is encrypted with separate keys
|
||||
* Encryption keys are properly secured
|
||||
|
||||
API Key Security
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
1. **Key Generation**
|
||||
|
||||
* Keys are generated using cryptographically secure random functions
|
||||
* Sufficient entropy (256 bits)
|
||||
* Keys follow a consistent format for validation
|
||||
|
||||
2. **Key Storage**
|
||||
|
||||
* Only key hashes are stored in the database
|
||||
* Secure comparison for validation
|
||||
* Keys are never logged or exposed in error messages
|
||||
|
||||
3. **Key Management**
|
||||
|
||||
* Keys can be rotated regularly
|
||||
* Unused keys are automatically expired
|
||||
* Key usage is logged for audit purposes
|
||||
|
||||
Secure Development Practices
|
||||
--------------------------
|
||||
|
||||
Input Validation
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
1. **API Input Validation**
|
||||
|
||||
* All input is validated against schemas
|
||||
* Type checking and constraint validation
|
||||
* Protection against injection attacks
|
||||
* Input sanitization where appropriate
|
||||
|
||||
2. **Content Validation**
|
||||
|
||||
* Content is scanned for malicious elements
|
||||
* HTML/Markdown sanitization
|
||||
* File upload validation and scanning
|
||||
|
||||
3. **Error Handling**
|
||||
|
||||
* Secure error handling that doesn't leak sensitive information
|
||||
* Consistent error responses
|
||||
* Detailed internal logging for troubleshooting
|
||||
|
||||
Dependency Management
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Dependency Scanning**
|
||||
|
||||
* Regular scanning for vulnerable dependencies
|
||||
* Automated updates for security patches
|
||||
* Dependency pinning for stability
|
||||
|
||||
2. **Minimal Dependencies**
|
||||
|
||||
* Only necessary dependencies are included
|
||||
* Regular dependency audits
|
||||
* Preference for well-maintained libraries
|
||||
|
||||
3. **Containerization**
|
||||
|
||||
* Minimal base images
|
||||
* Non-root container execution
|
||||
* Image scanning for vulnerabilities
|
||||
|
||||
Logging and Monitoring
|
||||
--------------------
|
||||
|
||||
Security Logging
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
1. **Authentication Events**
|
||||
|
||||
* Login attempts (successful and failed)
|
||||
* Password changes and resets
|
||||
* API key creation and usage
|
||||
* Session management events
|
||||
|
||||
2. **Authorization Events**
|
||||
|
||||
* Permission checks
|
||||
* Access denials
|
||||
* Privilege escalation
|
||||
* Role changes
|
||||
|
||||
3. **System Events**
|
||||
|
||||
* Configuration changes
|
||||
* Service starts and stops
|
||||
* Database migrations
|
||||
* Backup and restore operations
|
||||
|
||||
Monitoring and Alerting
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Security Monitoring**
|
||||
|
||||
* Real-time monitoring for suspicious activities
|
||||
* Anomaly detection for unusual patterns
|
||||
* Rate limiting and abuse detection
|
||||
* Geographic anomaly detection
|
||||
|
||||
2. **Performance Monitoring**
|
||||
|
||||
* Resource usage tracking
|
||||
* API response time monitoring
|
||||
* Error rate monitoring
|
||||
* Database performance tracking
|
||||
|
||||
3. **Alerting**
|
||||
|
||||
* Immediate alerts for security incidents
|
||||
* Escalation procedures
|
||||
* On-call rotation
|
||||
* Incident response playbooks
|
||||
|
||||
Compliance and Privacy
|
||||
--------------------
|
||||
|
||||
Data Governance
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **Data Classification**
|
||||
|
||||
* Clear classification of data sensitivity
|
||||
* Handling procedures for each classification
|
||||
* Access controls based on classification
|
||||
* Retention policies by data type
|
||||
|
||||
2. **Data Minimization**
|
||||
|
||||
* Only necessary data is collected
|
||||
* Automatic data pruning
|
||||
* Anonymization where possible
|
||||
* Purpose limitation
|
||||
|
||||
3. **User Consent**
|
||||
|
||||
* Clear consent mechanisms
|
||||
* Granular permission options
|
||||
* Easy consent withdrawal
|
||||
* Consent records
|
||||
|
||||
Privacy Features
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **User Privacy Controls**
|
||||
|
||||
* Data export functionality
|
||||
* Account deletion
|
||||
* Privacy settings management
|
||||
* Usage tracking opt-out
|
||||
|
||||
2. **Data Portability**
|
||||
|
||||
* Export in standard formats
|
||||
* Complete data export
|
||||
* Machine-readable formats
|
||||
* Import capabilities
|
||||
|
||||
3. **Transparency**
|
||||
|
||||
* Clear privacy policy
|
||||
* Data usage explanations
|
||||
* Third-party data sharing disclosure
|
||||
* Processing activities documentation
|
||||
|
||||
Security Testing
|
||||
--------------
|
||||
|
||||
Vulnerability Management
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Security Testing**
|
||||
|
||||
* Regular penetration testing
|
||||
* Static application security testing (SAST)
|
||||
* Dynamic application security testing (DAST)
|
||||
* Software composition analysis (SCA)
|
||||
|
||||
2. **Bug Bounty Program**
|
||||
|
||||
* Responsible disclosure policy
|
||||
* Security researcher engagement
|
||||
* Vulnerability triage process
|
||||
* Remediation tracking
|
||||
|
||||
3. **Security Reviews**
|
||||
|
||||
* Code reviews with security focus
|
||||
* Architecture security reviews
|
||||
* Threat modeling
|
||||
* Security design reviews
|
||||
|
||||
Incident Response
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Incident Response Plan**
|
||||
|
||||
* Defined incident response procedures
|
||||
* Roles and responsibilities
|
||||
* Communication templates
|
||||
* Escalation paths
|
||||
|
||||
2. **Breach Notification**
|
||||
|
||||
* Legal compliance with notification requirements
|
||||
* User communication plan
|
||||
* Regulatory reporting procedures
|
||||
* Post-incident analysis
|
||||
|
||||
3. **Recovery Procedures**
|
||||
|
||||
* Backup and restore testing
|
||||
* Business continuity planning
|
||||
* Disaster recovery procedures
|
||||
* Service level objectives
|
||||
|
||||
Security Roadmap
|
||||
--------------
|
||||
|
||||
Planned Security Enhancements
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Short-term (0-6 months)**
|
||||
|
||||
* Implement multi-factor authentication
|
||||
* Enhance API key management
|
||||
* Improve security logging
|
||||
* Conduct initial penetration test
|
||||
|
||||
2. **Medium-term (6-12 months)**
|
||||
|
||||
* Implement security information and event management (SIEM)
|
||||
* Enhance data encryption
|
||||
* Develop comprehensive security training
|
||||
* Implement automated security testing in CI/CD
|
||||
|
||||
3. **Long-term (12+ months)**
|
||||
|
||||
* Achieve SOC 2 compliance
|
||||
* Implement advanced threat protection
|
||||
* Develop zero-trust architecture
|
||||
* Enhance privacy features for international compliance
|
||||
39
docs/changelog.rst
Normal file
39
docs/changelog.rst
Normal file
@@ -0,0 +1,39 @@
|
||||
Changelog
|
||||
=========
|
||||
|
||||
Version 0.1.0 (Initial Release)
|
||||
-----------------------------
|
||||
|
||||
* Initial release of AI-Writer
|
||||
* Support for LinkedIn, Twitter, and blog content generation
|
||||
* Basic web research capabilities
|
||||
* SQLite database integration
|
||||
* Streamlit UI
|
||||
|
||||
Version 0.2.0
|
||||
-----------
|
||||
|
||||
* Added Facebook content generation
|
||||
* Enhanced web research with async crawling
|
||||
* Improved UI with sidebar navigation
|
||||
* Added basic analytics dashboard
|
||||
* Vector database integration for semantic search
|
||||
|
||||
Version 0.3.0
|
||||
-----------
|
||||
|
||||
* Added YouTube content generation
|
||||
* Integrated Google Gemini models
|
||||
* Enhanced SEO tools
|
||||
* Added content planning calendar
|
||||
* Improved error handling and logging
|
||||
|
||||
Version 0.4.0 (Current)
|
||||
--------------------
|
||||
|
||||
* Added image generation capabilities
|
||||
* Enhanced personalization options
|
||||
* Improved database performance
|
||||
* Added content versioning
|
||||
* Enhanced analytics with visualization
|
||||
* Added support for multiple AI providers
|
||||
40
docs/conf.py
Normal file
40
docs/conf.py
Normal file
@@ -0,0 +1,40 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
project = 'AI-Writer'
|
||||
copyright = '2025, AJaySi'
|
||||
author = 'AJaySi'
|
||||
|
||||
version = '1.0'
|
||||
release = '1.0'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.viewcode',
|
||||
'sphinx.ext.napoleon',
|
||||
'sphinx.ext.intersphinx',
|
||||
]
|
||||
|
||||
# Add path to the project
|
||||
import os
|
||||
import sys
|
||||
sys.path.insert(0, os.path.abspath('..'))
|
||||
|
||||
templates_path = ['_templates']
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_static_path = ['_static']
|
||||
5
docs/contributing.rst
Normal file
5
docs/contributing.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
.. include:: ../CONTRIBUTING.md
|
||||
:parser: myst_parser.sphinx_
|
||||
230
docs/developer/coding_standards.rst
Normal file
230
docs/developer/coding_standards.rst
Normal file
@@ -0,0 +1,230 @@
|
||||
Coding Standards
|
||||
===============
|
||||
|
||||
This document outlines the coding standards and best practices for contributing to the AI-Writer project.
|
||||
|
||||
Code Style
|
||||
---------
|
||||
|
||||
AI-Writer follows the PEP 8 style guide for Python code with some additional guidelines:
|
||||
|
||||
1. **Indentation**
|
||||
|
||||
* Use 4 spaces for indentation (no tabs)
|
||||
* Continuation lines should align with the opening delimiter or be indented by 4 spaces
|
||||
|
||||
2. **Line Length**
|
||||
|
||||
* Maximum line length is 100 characters
|
||||
* For docstrings and comments, limit to 80 characters
|
||||
|
||||
3. **Imports**
|
||||
|
||||
* Group imports in the following order:
|
||||
1. Standard library imports
|
||||
2. Related third-party imports
|
||||
3. Local application/library specific imports
|
||||
* Within each group, imports should be sorted alphabetically
|
||||
* Use absolute imports rather than relative imports
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Standard library
|
||||
import os
|
||||
import sys
|
||||
from typing import Dict, List, Optional
|
||||
|
||||
# Third-party
|
||||
import numpy as np
|
||||
import pandas as pd
|
||||
import streamlit as st
|
||||
|
||||
# Local
|
||||
from lib.database import models
|
||||
from lib.utils import helpers
|
||||
|
||||
4. **Naming Conventions**
|
||||
|
||||
* Classes: `CamelCase`
|
||||
* Functions and variables: `snake_case`
|
||||
* Constants: `UPPER_CASE`
|
||||
* Private methods and variables: `_leading_underscore`
|
||||
* Protected methods and variables: `__double_leading_underscore`
|
||||
|
||||
5. **String Formatting**
|
||||
|
||||
* Use f-strings for string formatting when possible
|
||||
* For older Python versions, use `.format()` method
|
||||
* Avoid using `%` formatting
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Preferred
|
||||
name = "World"
|
||||
greeting = f"Hello, {name}!"
|
||||
|
||||
# Acceptable
|
||||
greeting = "Hello, {}!".format(name)
|
||||
|
||||
# Avoid
|
||||
greeting = "Hello, %s!" % name
|
||||
|
||||
Documentation
|
||||
------------
|
||||
|
||||
1. **Docstrings**
|
||||
|
||||
* Use Google-style docstrings
|
||||
* All modules, classes, and functions should have docstrings
|
||||
* Include type hints in function signatures
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def generate_content(prompt: str, max_tokens: int = 100) -> str:
|
||||
"""Generate content using the AI model.
|
||||
|
||||
Args:
|
||||
prompt: The input prompt for content generation.
|
||||
max_tokens: Maximum number of tokens to generate.
|
||||
|
||||
Returns:
|
||||
The generated content as a string.
|
||||
|
||||
Raises:
|
||||
ValueError: If the prompt is empty or max_tokens is negative.
|
||||
"""
|
||||
if not prompt:
|
||||
raise ValueError("Prompt cannot be empty")
|
||||
|
||||
if max_tokens < 0:
|
||||
raise ValueError("max_tokens must be a positive integer")
|
||||
|
||||
# Implementation...
|
||||
return generated_content
|
||||
|
||||
2. **Comments**
|
||||
|
||||
* Use comments sparingly and only when necessary
|
||||
* Focus on explaining "why" rather than "what"
|
||||
* Keep comments up-to-date with code changes
|
||||
|
||||
3. **Type Hints**
|
||||
|
||||
* Use type hints for all function parameters and return values
|
||||
* Use `Optional` for parameters that can be None
|
||||
* Use `Union` for parameters that can be multiple types
|
||||
* Use `Any` only when absolutely necessary
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from typing import Dict, List, Optional, Union
|
||||
|
||||
def process_data(
|
||||
data: Union[Dict[str, str], List[str]],
|
||||
config: Optional[Dict[str, str]] = None
|
||||
) -> List[str]:
|
||||
"""Process the input data."""
|
||||
# Implementation...
|
||||
return processed_data
|
||||
|
||||
Error Handling
|
||||
-------------
|
||||
|
||||
1. **Exceptions**
|
||||
|
||||
* Use specific exception types rather than generic exceptions
|
||||
* Handle exceptions at the appropriate level
|
||||
* Include meaningful error messages
|
||||
* Log exceptions with appropriate context
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
try:
|
||||
result = api_client.fetch_data(query)
|
||||
except ConnectionError as e:
|
||||
logger.error(f"Failed to connect to API: {e}")
|
||||
raise ServiceUnavailableError("API service is currently unavailable") from e
|
||||
except ValueError as e:
|
||||
logger.warning(f"Invalid query parameter: {e}")
|
||||
raise InvalidParameterError(f"Invalid query parameter: {e}") from e
|
||||
|
||||
2. **Validation**
|
||||
|
||||
* Validate input parameters early
|
||||
* Use assertions for internal checks (not for input validation)
|
||||
* Return meaningful error messages for invalid inputs
|
||||
|
||||
Testing
|
||||
------
|
||||
|
||||
1. **Test Coverage**
|
||||
|
||||
* Aim for at least 80% test coverage for new code
|
||||
* Write unit tests for all new functions and classes
|
||||
* Include integration tests for complex interactions
|
||||
|
||||
2. **Test Organization**
|
||||
|
||||
* Place tests in the `tests/` directory
|
||||
* Mirror the package structure in the test directory
|
||||
* Name test files with `test_` prefix
|
||||
|
||||
3. **Test Naming**
|
||||
|
||||
* Use descriptive test names that explain what is being tested
|
||||
* Follow the pattern `test_<function_name>_<scenario>_<expected_result>`
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def test_generate_content_empty_prompt_raises_value_error():
|
||||
"""Test that generate_content raises ValueError for empty prompts."""
|
||||
with pytest.raises(ValueError, match="Prompt cannot be empty"):
|
||||
generate_content("")
|
||||
|
||||
Performance Considerations
|
||||
------------------------
|
||||
|
||||
1. **Resource Usage**
|
||||
|
||||
* Be mindful of memory usage, especially for large datasets
|
||||
* Use generators and iterators for large data processing
|
||||
* Consider using async functions for I/O-bound operations
|
||||
|
||||
2. **Optimization**
|
||||
|
||||
* Optimize for readability first, then performance
|
||||
* Document performance-critical sections
|
||||
* Include benchmarks for performance-sensitive code
|
||||
|
||||
Security Best Practices
|
||||
---------------------
|
||||
|
||||
1. **API Keys and Secrets**
|
||||
|
||||
* Never hardcode API keys or secrets
|
||||
* Use environment variables or secure storage
|
||||
* Implement proper access controls for sensitive data
|
||||
|
||||
2. **Input Validation**
|
||||
|
||||
* Validate and sanitize all user inputs
|
||||
* Use parameterized queries for database operations
|
||||
* Implement proper authentication and authorization
|
||||
|
||||
3. **Dependency Management**
|
||||
|
||||
* Keep dependencies up-to-date
|
||||
* Regularly check for security vulnerabilities
|
||||
* Pin dependency versions for reproducibility
|
||||
39
docs/developer/index.rst
Normal file
39
docs/developer/index.rst
Normal file
@@ -0,0 +1,39 @@
|
||||
Developer Guide
|
||||
==============
|
||||
|
||||
This section provides comprehensive documentation for developers who want to contribute to or extend the AI-Writer platform.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Developer Documentation:
|
||||
|
||||
setup
|
||||
architecture
|
||||
coding_standards
|
||||
testing
|
||||
extending
|
||||
|
||||
Development Environment Setup
|
||||
---------------------------
|
||||
|
||||
.. include:: setup.rst
|
||||
|
||||
Architecture Overview
|
||||
-------------------
|
||||
|
||||
.. include:: architecture.rst
|
||||
|
||||
Coding Standards
|
||||
--------------
|
||||
|
||||
.. include:: coding_standards.rst
|
||||
|
||||
Testing Guidelines
|
||||
----------------
|
||||
|
||||
.. include:: testing.rst
|
||||
|
||||
Extending AI-Writer
|
||||
-----------------
|
||||
|
||||
.. include:: extending.rst
|
||||
176
docs/developer/setup.rst
Normal file
176
docs/developer/setup.rst
Normal file
@@ -0,0 +1,176 @@
|
||||
Development Environment Setup
|
||||
============================
|
||||
|
||||
This guide will help you set up a development environment for contributing to the AI-Writer project.
|
||||
|
||||
Prerequisites
|
||||
------------
|
||||
|
||||
Before setting up the development environment, ensure you have the following installed:
|
||||
|
||||
* Python 3.9 or higher
|
||||
* Git
|
||||
* A code editor (VS Code, PyCharm, etc.)
|
||||
* Docker (optional, for containerized development)
|
||||
|
||||
Setting Up the Development Environment
|
||||
------------------------------------
|
||||
|
||||
1. **Clone the Repository**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/AJaySi/AI-Writer.git
|
||||
cd AI-Writer
|
||||
|
||||
2. **Create a Virtual Environment**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
|
||||
3. **Install Development Dependencies**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install -r requirements.txt
|
||||
pip install -r requirements-dev.txt # Install development dependencies
|
||||
|
||||
4. **Set Up Pre-commit Hooks**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install pre-commit
|
||||
pre-commit install
|
||||
|
||||
5. **Configure Environment Variables**
|
||||
|
||||
Create a `.env` file in the project root with the following variables:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# API Keys
|
||||
OPENAI_API_KEY=your_openai_api_key
|
||||
GOOGLE_API_KEY=your_google_api_key
|
||||
|
||||
# Database Configuration
|
||||
DB_PATH=sqlite:///./data/alwrity.db
|
||||
VECTOR_DB_PATH=./data/vectordb
|
||||
|
||||
# Development Settings
|
||||
DEBUG=True
|
||||
ENVIRONMENT=development
|
||||
|
||||
6. **Initialize the Database**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python -c "from lib.database.db_manager import init_db; init_db()"
|
||||
|
||||
7. **Run the Development Server**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
streamlit run alwrity.py
|
||||
|
||||
Development Workflow
|
||||
------------------
|
||||
|
||||
1. **Create a Feature Branch**
|
||||
|
||||
Always create a new branch for your changes:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git checkout -b feature/your-feature-name
|
||||
|
||||
2. **Make Changes and Test**
|
||||
|
||||
Implement your changes and test them thoroughly:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Run tests
|
||||
pytest
|
||||
|
||||
# Run linting
|
||||
flake8
|
||||
|
||||
# Run type checking
|
||||
mypy .
|
||||
|
||||
3. **Commit Changes**
|
||||
|
||||
Follow the commit message conventions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git add .
|
||||
git commit -m "feat: add new feature"
|
||||
|
||||
4. **Push Changes and Create a Pull Request**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git push origin feature/your-feature-name
|
||||
|
||||
Then create a pull request on GitHub.
|
||||
|
||||
Using Docker for Development
|
||||
--------------------------
|
||||
|
||||
For containerized development:
|
||||
|
||||
1. **Build the Development Container**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker build -t alwrity-dev -f Dockerfile.dev .
|
||||
|
||||
2. **Run the Development Container**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run -p 8501:8501 -v $(pwd):/app alwrity-dev
|
||||
|
||||
3. **Using Docker Compose**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker-compose -f docker-compose.dev.yml up
|
||||
|
||||
Troubleshooting
|
||||
-------------
|
||||
|
||||
Common development setup issues:
|
||||
|
||||
1. **Dependency Conflicts**
|
||||
|
||||
If you encounter dependency conflicts, try:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install --upgrade pip
|
||||
pip install -r requirements.txt --no-cache-dir
|
||||
|
||||
2. **Database Migration Issues**
|
||||
|
||||
If you encounter database migration issues:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Reset the database
|
||||
rm -rf ./data/alwrity.db
|
||||
rm -rf ./data/vectordb
|
||||
|
||||
# Reinitialize
|
||||
python -c "from lib.database.db_manager import init_db; init_db()"
|
||||
|
||||
3. **Streamlit Port Already in Use**
|
||||
|
||||
If the Streamlit port is already in use:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
streamlit run alwrity.py --server.port=8502
|
||||
34
docs/index.rst
Normal file
34
docs/index.rst
Normal file
@@ -0,0 +1,34 @@
|
||||
.. AI-Writer documentation master file, created by
|
||||
sphinx-quickstart on Fri Apr 18 08:15:28 2025.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Welcome to AI-Writer's documentation!
|
||||
=====================================
|
||||
|
||||
AI-Writer (Alwrity) is an AI-powered content creation platform that helps you generate high-quality content for various platforms including blogs, social media, and marketing materials.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
introduction
|
||||
installation
|
||||
usage
|
||||
api/index
|
||||
developer/index
|
||||
architecture/index
|
||||
roadmap
|
||||
contributing
|
||||
changelog
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
* Multi-platform content generation (LinkedIn, Twitter, Blog posts, etc.)
|
||||
* AI-powered research and content optimization
|
||||
* Database integration for content storage and retrieval
|
||||
* Analytics dashboard for content performance
|
||||
* Customizable templates and personalization options
|
||||
* Integration with various AI providers (OpenAI, Google Gemini, etc.)
|
||||
|
||||
117
docs/installation.rst
Normal file
117
docs/installation.rst
Normal file
@@ -0,0 +1,117 @@
|
||||
Installation
|
||||
============
|
||||
|
||||
System Requirements
|
||||
------------------
|
||||
|
||||
Before installing AI-Writer, ensure your system meets the following requirements:
|
||||
|
||||
* Python 3.9 or higher
|
||||
* 4GB RAM minimum (8GB recommended)
|
||||
* 2GB free disk space
|
||||
* Internet connection for AI API access
|
||||
|
||||
Installation Methods
|
||||
------------------
|
||||
|
||||
There are several ways to install and run AI-Writer:
|
||||
|
||||
Method 1: Using pip (Recommended)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/AJaySi/AI-Writer.git
|
||||
cd AI-Writer
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Run the application
|
||||
streamlit run alwrity.py
|
||||
|
||||
Method 2: Using Docker
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/AJaySi/AI-Writer.git
|
||||
cd AI-Writer
|
||||
|
||||
# Build and run with Docker Compose
|
||||
docker-compose up -d
|
||||
|
||||
Method 3: Manual Installation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you prefer to install dependencies manually:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/AJaySi/AI-Writer.git
|
||||
cd AI-Writer
|
||||
|
||||
# Create a virtual environment (optional but recommended)
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
|
||||
# Install core dependencies
|
||||
pip install streamlit openai google-generativeai chromadb sqlalchemy
|
||||
|
||||
# Install additional dependencies as needed
|
||||
pip install beautifulsoup4 requests pandas matplotlib plotly
|
||||
|
||||
# Run the application
|
||||
streamlit run alwrity.py
|
||||
|
||||
Configuration
|
||||
------------
|
||||
|
||||
After installation, you'll need to configure AI-Writer with your API keys:
|
||||
|
||||
1. Launch the application using `streamlit run alwrity.py`
|
||||
2. Follow the setup wizard to configure:
|
||||
- AI provider API keys (OpenAI, Google Gemini, etc.)
|
||||
- Research tools settings
|
||||
- Database configuration
|
||||
- Personalization options
|
||||
|
||||
The configuration will be saved and can be modified later through the settings page.
|
||||
|
||||
Troubleshooting
|
||||
--------------
|
||||
|
||||
Common Installation Issues
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Dependency Conflicts**
|
||||
|
||||
If you encounter dependency conflicts, try installing in a fresh virtual environment:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python -m venv fresh_venv
|
||||
source fresh_venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
2. **Port Already in Use**
|
||||
|
||||
If Streamlit cannot start because the port is in use:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
streamlit run alwrity.py --server.port=8501
|
||||
|
||||
3. **Database Connection Issues**
|
||||
|
||||
Ensure you have proper permissions for creating and accessing database files:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Check permissions
|
||||
chmod 755 -R ./data
|
||||
|
||||
For additional help, please refer to the project's GitHub issues page or contact the maintainers.
|
||||
56
docs/introduction.rst
Normal file
56
docs/introduction.rst
Normal file
@@ -0,0 +1,56 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
What is AI-Writer?
|
||||
-----------------
|
||||
|
||||
AI-Writer (Alwrity) is a comprehensive AI-powered content creation platform designed to help content creators, marketers, and businesses generate high-quality content efficiently. The platform leverages advanced language models and AI technologies to assist in creating various types of content, from social media posts to full-length articles.
|
||||
|
||||
Key Features
|
||||
-----------
|
||||
|
||||
1. **Multi-Platform Content Generation**
|
||||
|
||||
* LinkedIn content (posts, articles, profiles)
|
||||
* Twitter/X posts and threads
|
||||
* Blog articles and SEO-optimized content
|
||||
* Marketing copy and email templates
|
||||
|
||||
2. **AI Research Integration**
|
||||
|
||||
* Web crawling for relevant information
|
||||
* Content summarization
|
||||
* Fact-checking capabilities
|
||||
* Citation and reference management
|
||||
|
||||
3. **Database Integration**
|
||||
|
||||
* Content storage and retrieval
|
||||
* Vector database for semantic search
|
||||
* Content versioning and history
|
||||
|
||||
4. **Analytics Dashboard**
|
||||
|
||||
* Content performance metrics
|
||||
* Usage statistics
|
||||
* AI model performance analysis
|
||||
|
||||
5. **Customization Options**
|
||||
|
||||
* Personalized content templates
|
||||
* Brand voice and tone settings
|
||||
* Custom workflows
|
||||
|
||||
6. **Multiple AI Provider Support**
|
||||
|
||||
* OpenAI (GPT models)
|
||||
* Google Gemini
|
||||
* Anthropic Claude (coming soon)
|
||||
* Local models (coming soon)
|
||||
|
||||
Project History
|
||||
--------------
|
||||
|
||||
AI-Writer was created to address the growing need for high-quality content creation at scale. The project aims to democratize access to advanced AI writing capabilities while maintaining a focus on quality, accuracy, and ethical content generation.
|
||||
|
||||
The platform continues to evolve with new features and improvements based on user feedback and advancements in AI technology.
|
||||
35
docs/make.bat
Normal file
35
docs/make.bat
Normal file
@@ -0,0 +1,35 @@
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=.
|
||||
set BUILDDIR=_build
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.https://www.sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
||||
374
docs/roadmap.rst
Normal file
374
docs/roadmap.rst
Normal file
@@ -0,0 +1,374 @@
|
||||
Roadmap
|
||||
=======
|
||||
|
||||
This document outlines the planned development roadmap for the AI-Writer project, including upcoming features, improvements, and long-term goals.
|
||||
|
||||
Status Indicators
|
||||
---------------
|
||||
|
||||
- **In Progress**: Currently being developed
|
||||
- **Planned**: Scheduled for upcoming development cycles
|
||||
- **Researching**: Under investigation and evaluation
|
||||
- **Completed**: Released and available
|
||||
|
||||
Short-Term Goals (Q2 2025: April - June)
|
||||
-------------------------------------
|
||||
|
||||
1. **Core Platform Enhancements**
|
||||
|
||||
* **Performance Optimization** (In Progress)
|
||||
- Reduce content generation time by 30%
|
||||
- Optimize memory usage for large content pieces
|
||||
- Implement caching for frequently used research data
|
||||
|
||||
* **Multi-language Support** (Planned)
|
||||
- Add support for Spanish, French, and German content generation
|
||||
- Implement language-specific research capabilities
|
||||
- Create language-specific SEO optimization
|
||||
|
||||
* **User Interface Refresh** (Planned)
|
||||
- Redesign main dashboard for improved usability
|
||||
- Implement dark mode
|
||||
- Add customizable workspace layouts
|
||||
|
||||
2. **AI Provider Integrations**
|
||||
|
||||
* **Anthropic Claude Integration** (In Progress)
|
||||
- Add support for Claude 3 models
|
||||
- Optimize for long-form content generation
|
||||
- Implement specialized prompting techniques
|
||||
|
||||
* **Local LLM Support** (Planned)
|
||||
- Integration with Ollama for local model deployment
|
||||
- Support for Llama 3 and Mistral models
|
||||
- Optimized inference for resource-constrained environments
|
||||
|
||||
* **Model Fallback System** (Planned)
|
||||
- Automatic failover between AI providers
|
||||
- Smart routing based on content type
|
||||
- Performance monitoring and optimization
|
||||
|
||||
3. **Content Generation Improvements**
|
||||
|
||||
* **Enhanced Blog Writer** (In Progress)
|
||||
- Add support for more blog formats (listicles, how-to guides, etc.)
|
||||
- Implement advanced outline generation
|
||||
- Add competitor content analysis
|
||||
|
||||
* **AI Script Writer** (Planned)
|
||||
- Create specialized writer for video scripts
|
||||
- Support multiple video formats (YouTube, TikTok, Instagram)
|
||||
- Add scene breakdown and shot suggestions
|
||||
|
||||
* **Technical Content Writer** (Planned)
|
||||
- Specialized writer for technical documentation
|
||||
- Code snippet generation and formatting
|
||||
- Technical accuracy verification
|
||||
|
||||
Medium-Term Goals (Q3 2025: July - September)
|
||||
------------------------------------------
|
||||
|
||||
1. **Advanced Analytics**
|
||||
|
||||
* **Analytics Dashboard** (Planned)
|
||||
- Content performance tracking
|
||||
- Usage statistics and insights
|
||||
- AI model performance metrics
|
||||
- Export options for analytics data
|
||||
|
||||
* **Content Audit Tools** (Planned)
|
||||
- Analyze existing content
|
||||
- Identify improvement opportunities
|
||||
- Generate update recommendations
|
||||
- Content quality scoring
|
||||
|
||||
* **Predictive Analytics** (Researching)
|
||||
- Content performance prediction
|
||||
- Trend analysis for content topics
|
||||
- Audience engagement forecasting
|
||||
|
||||
2. **Collaboration Features**
|
||||
|
||||
* **Multi-user Platform** (Planned)
|
||||
- Role-based access control
|
||||
- Team workspaces for collaborative content creation
|
||||
- User management and permissions
|
||||
|
||||
* **Content Workflow** (Planned)
|
||||
- Content review and approval workflows
|
||||
- Comment and feedback system
|
||||
- Version tracking and comparison
|
||||
|
||||
* **Real-time Collaboration** (Researching)
|
||||
- Simultaneous editing capabilities
|
||||
- Presence indicators
|
||||
- Change tracking and attribution
|
||||
|
||||
3. **Integration Capabilities**
|
||||
|
||||
* **Publishing Integrations** (Planned)
|
||||
- WordPress plugin for direct publishing
|
||||
- Integration with social media platforms
|
||||
- CMS connectors (Drupal, Joomla, etc.)
|
||||
|
||||
* **Marketing Platform Connections** (Planned)
|
||||
- Email marketing platform integrations
|
||||
- Marketing automation connections
|
||||
- Analytics platform integrations
|
||||
|
||||
* **API Expansion** (Researching)
|
||||
- Comprehensive REST API
|
||||
- Webhook integrations
|
||||
- Developer documentation and SDKs
|
||||
|
||||
4. **Content Research Tools**
|
||||
|
||||
* **Advanced Web Research** (In Progress)
|
||||
- Multi-source research aggregation
|
||||
- Research depth controls
|
||||
- Improve citation and source tracking
|
||||
|
||||
* **Semantic SEO Tools** (Planned)
|
||||
- Entity-based content optimization
|
||||
- Topic cluster mapping
|
||||
- Natural language query optimization
|
||||
|
||||
* **Academic Research Integration** (Researching)
|
||||
- Access to academic databases
|
||||
- Citation generation
|
||||
- Research paper summarization
|
||||
|
||||
Long-Term Goals (Q4 2025 and Beyond)
|
||||
--------------------------------
|
||||
|
||||
1. **AI and ML Enhancements**
|
||||
|
||||
* **Multimodal Content Creation** (Researching)
|
||||
- Integrated text, image, and video generation
|
||||
- Cross-format content consistency
|
||||
- Single-prompt multi-format generation
|
||||
|
||||
* **Custom AI Models** (Researching)
|
||||
- Fine-tuned models for specific content types
|
||||
- Implement reinforcement learning from user feedback
|
||||
- Domain-specific knowledge integration
|
||||
|
||||
* **Voice and Audio Integration** (Researching)
|
||||
- Voice-to-content conversion
|
||||
- Content-to-voice generation
|
||||
- Podcast and audio content creation
|
||||
|
||||
2. **Enterprise Features**
|
||||
|
||||
* **Enterprise Security** (Planned)
|
||||
- Single sign-on (SSO) integration
|
||||
- Advanced security controls
|
||||
- Custom branding options
|
||||
|
||||
* **Compliance and Governance** (Planned)
|
||||
- Audit logging and compliance reporting
|
||||
- Data retention and privacy controls
|
||||
- Role-based permissions and workflows
|
||||
|
||||
* **Enterprise Support** (Planned)
|
||||
- SLA-based support options
|
||||
- Dedicated customer success
|
||||
- Custom training and onboarding
|
||||
|
||||
3. **Content Ecosystem**
|
||||
|
||||
* **AI Agent Ecosystem** (Researching)
|
||||
- Specialized AI agents for different tasks
|
||||
- Agent collaboration framework
|
||||
- Custom agent creation
|
||||
|
||||
* **Content Marketplace** (Researching)
|
||||
- Templates and content frameworks
|
||||
- Plugin system for extending functionality
|
||||
- Community contributions and sharing
|
||||
|
||||
* **Developer Platform** (Planned)
|
||||
- API for third-party integrations
|
||||
- Developer SDK for custom extensions
|
||||
- Comprehensive documentation and examples
|
||||
|
||||
4. **Advanced Personalization**
|
||||
|
||||
* **Adaptive Content Generation** (Researching)
|
||||
- User behavior-based recommendations
|
||||
- Personalized content generation
|
||||
- Learning from user preferences
|
||||
|
||||
* **Audience Intelligence** (Planned)
|
||||
- Audience segmentation and targeting
|
||||
- Demographic and psychographic analysis
|
||||
- Content optimization by audience
|
||||
|
||||
* **Testing Framework** (Planned)
|
||||
- A/B testing for content variations
|
||||
- Performance measurement and analysis
|
||||
- Automated optimization based on results
|
||||
|
||||
5. **Global Expansion**
|
||||
|
||||
* **Comprehensive Localization** (Planned)
|
||||
- Support for 20+ languages
|
||||
- Region-specific content templates
|
||||
- Localized user interface
|
||||
|
||||
* **International Compliance** (Planned)
|
||||
- Compliance with international regulations
|
||||
- Regional data storage options
|
||||
- Privacy controls by region
|
||||
|
||||
* **Global Community** (Researching)
|
||||
- International user communities
|
||||
- Region-specific support and resources
|
||||
- Local partnerships and integrations
|
||||
|
||||
Technical Debt and Infrastructure Improvements
|
||||
-------------------------------------------
|
||||
|
||||
In addition to new features, we plan to address the following technical debt items:
|
||||
|
||||
1. **Code Quality** (In Progress)
|
||||
|
||||
* Refactor core modules for better separation of concerns
|
||||
* Implement consistent error handling
|
||||
* Add comprehensive type hints
|
||||
* Standardize logging across all modules
|
||||
* Implement design patterns for maintainability
|
||||
|
||||
2. **Testing Infrastructure** (Planned)
|
||||
|
||||
* Implement CI/CD pipeline with GitHub Actions
|
||||
* Increase test coverage to 80%
|
||||
* Add integration and end-to-end tests
|
||||
* Implement performance benchmarking
|
||||
* Add security scanning and vulnerability testing
|
||||
|
||||
3. **Documentation** (In Progress)
|
||||
|
||||
* Complete internal code documentation
|
||||
* Create comprehensive architecture diagrams
|
||||
* Document all APIs and interfaces
|
||||
* Create developer guides for each module
|
||||
* Implement automated documentation generation
|
||||
|
||||
4. **Dependency Management** (Planned)
|
||||
|
||||
* Move from requirements.txt to Poetry
|
||||
* Pin and audit dependencies
|
||||
* Reduce unnecessary dependencies
|
||||
* Implement dependency injection for better testability
|
||||
* Create containerized development environment
|
||||
|
||||
5. **Infrastructure Modernization** (Researching)
|
||||
|
||||
* Containerization with Docker
|
||||
* Kubernetes deployment for scalability
|
||||
* Infrastructure as Code with Terraform
|
||||
* Monitoring and observability stack
|
||||
* Automated backup and disaster recovery
|
||||
|
||||
Recently Completed Features
|
||||
-----------------------
|
||||
|
||||
The following features have been recently completed and are available in the current version:
|
||||
|
||||
1. **Core Platform** (Completed)
|
||||
|
||||
* **Google Gemini Integration**
|
||||
- Added support for Google's Gemini Pro model
|
||||
- Implemented efficient token usage
|
||||
- Optimized for specific content types
|
||||
|
||||
* **ChromaDB Vector Storage**
|
||||
- Implemented vector database for semantic search
|
||||
- Content similarity analysis
|
||||
- Efficient content retrieval
|
||||
|
||||
* **Streamlit UI Improvements**
|
||||
- Enhanced user interface
|
||||
- Better navigation and controls
|
||||
- Improved mobile responsiveness
|
||||
|
||||
2. **Content Generation** (Completed)
|
||||
|
||||
* **AI News Article Writer**
|
||||
- Specialized writer for news content
|
||||
- Citation support for factual accuracy
|
||||
- Balanced reporting capabilities
|
||||
|
||||
* **SEO Optimization Tools**
|
||||
- On-page SEO analysis
|
||||
- Keyword optimization
|
||||
- Meta description generator
|
||||
|
||||
3. **Research Tools** (Completed)
|
||||
|
||||
* **Tavily AI Research Integration**
|
||||
- Added support for AI-powered web research
|
||||
- Enhanced factual accuracy in content
|
||||
- Improved research depth and breadth
|
||||
|
||||
* **Exa Search Integration**
|
||||
- Semantic search capabilities
|
||||
- Relevant source discovery
|
||||
- Research summarization
|
||||
|
||||
Community Contributions
|
||||
---------------------
|
||||
|
||||
We welcome community contributions in the following areas:
|
||||
|
||||
1. **New Content Types**
|
||||
|
||||
* Templates for specialized industries
|
||||
* Support for additional platforms
|
||||
* Niche content formats
|
||||
* Industry-specific optimizations
|
||||
|
||||
2. **Integrations**
|
||||
|
||||
* Additional AI provider integrations
|
||||
* CMS and publishing platform connectors
|
||||
* Analytics and reporting tools
|
||||
* Marketing automation platforms
|
||||
|
||||
3. **Documentation and Examples**
|
||||
|
||||
* Usage examples and tutorials
|
||||
* Translations of documentation
|
||||
* Case studies and best practices
|
||||
* Video tutorials and demonstrations
|
||||
|
||||
4. **Testing and Quality Assurance**
|
||||
|
||||
* Bug reports and fixes
|
||||
* Performance improvements
|
||||
* Security audits
|
||||
* Accessibility enhancements
|
||||
|
||||
Feedback and Prioritization
|
||||
-------------------------
|
||||
|
||||
This roadmap is subject to change based on user feedback and community needs. We prioritize features based on:
|
||||
|
||||
1. User impact and demand
|
||||
2. Technical feasibility
|
||||
3. Strategic alignment
|
||||
4. Resource availability
|
||||
5. Community interest
|
||||
|
||||
To provide feedback on the roadmap or suggest new features, please:
|
||||
|
||||
* Open an issue on GitHub
|
||||
* Discuss in the community forums
|
||||
* Contact the maintainers directly
|
||||
* Join our monthly roadmap review calls
|
||||
|
||||
We review and update the roadmap quarterly to ensure it reflects current priorities and progress.
|
||||
|
||||
.. note::
|
||||
Last updated: April 18, 2025. For the most current roadmap, please visit our GitHub repository or project website.
|
||||
529
docs/tutorials/advanced_content_generation.rst
Normal file
529
docs/tutorials/advanced_content_generation.rst
Normal file
@@ -0,0 +1,529 @@
|
||||
Advanced Content Generation Techniques
|
||||
=================================
|
||||
|
||||
This tutorial covers advanced techniques for generating high-quality content with AI-Writer. You'll learn how to leverage the platform's advanced features to create more sophisticated, targeted, and effective content.
|
||||
|
||||
Prerequisites
|
||||
------------
|
||||
|
||||
Before proceeding with this tutorial, you should:
|
||||
|
||||
* Have completed the [Getting Started](getting_started.rst) tutorial
|
||||
* Be familiar with basic content generation in AI-Writer
|
||||
* Have configured your API keys for advanced features
|
||||
|
||||
Advanced Research Techniques
|
||||
--------------------------
|
||||
|
||||
Combining Multiple Research Sources
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For comprehensive research, combine multiple sources:
|
||||
|
||||
1. **Configure Research Sources**:
|
||||
|
||||
* Navigate to the "Research Settings" in the sidebar
|
||||
* Enable multiple research providers:
|
||||
* Tavily AI for factual information
|
||||
* Exa for semantic search
|
||||
* SerperDev for SERP data
|
||||
* Custom URLs for specific sources
|
||||
|
||||
2. **Set Research Parameters**:
|
||||
|
||||
* Adjust depth for each source
|
||||
* Set relevance thresholds
|
||||
* Configure result limits
|
||||
|
||||
3. **Execute Multi-Source Research**:
|
||||
|
||||
* Use the "Advanced Research" button
|
||||
* Review combined research results
|
||||
* Save research for future use
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Example of multi-source research configuration
|
||||
research_config = {
|
||||
"tavily": {"enabled": True, "depth": "deep", "max_results": 5},
|
||||
"exa": {"enabled": True, "relevance_threshold": 0.7, "max_results": 3},
|
||||
"serper": {"enabled": True, "result_type": "organic", "max_results": 5},
|
||||
"custom_urls": ["https://example.com/resource1", "https://example.com/resource2"]
|
||||
}
|
||||
|
||||
Domain-Specific Research
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For specialized content, focus your research:
|
||||
|
||||
1. **Domain Filtering**:
|
||||
|
||||
* Specify domains to include or exclude
|
||||
* Set domain authority thresholds
|
||||
* Filter by publication date
|
||||
|
||||
2. **Expert Sources**:
|
||||
|
||||
* Include academic databases
|
||||
* Add industry publications
|
||||
* Include expert blogs and forums
|
||||
|
||||
3. **Competitive Analysis**:
|
||||
|
||||
* Research competitor content
|
||||
* Identify content gaps
|
||||
* Analyze top-performing content
|
||||
|
||||
Advanced Content Structuring
|
||||
--------------------------
|
||||
|
||||
Content Outlines with AI
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Create sophisticated content outlines:
|
||||
|
||||
1. **Generate Advanced Outline**:
|
||||
|
||||
* Use the "AI Outline Generator"
|
||||
* Specify content type and depth
|
||||
* Include research insights
|
||||
|
||||
2. **Customize Outline Structure**:
|
||||
|
||||
* Rearrange sections for better flow
|
||||
* Add custom sections
|
||||
* Specify section priorities
|
||||
|
||||
3. **Generate from Outline**:
|
||||
|
||||
* Use the outline as a framework
|
||||
* Generate content section by section
|
||||
* Maintain consistency across sections
|
||||
|
||||
Example outline structure:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Advanced Blog Post Structure
|
||||
|
||||
## Introduction
|
||||
- Hook: Surprising statistic or question
|
||||
- Context: Brief background on topic
|
||||
- Thesis: Main argument or purpose
|
||||
- Roadmap: What the reader will learn
|
||||
|
||||
## Section 1: Current Landscape
|
||||
- Industry overview
|
||||
- Key challenges
|
||||
- Recent developments
|
||||
|
||||
## Section 2: Core Concepts
|
||||
- Definition and explanation
|
||||
- Historical context
|
||||
- Practical applications
|
||||
|
||||
## Section 3: Case Studies
|
||||
- Real-world example 1
|
||||
- Real-world example 2
|
||||
- Lessons learned
|
||||
|
||||
## Section 4: Implementation Guide
|
||||
- Step-by-step process
|
||||
- Tools and resources
|
||||
- Common pitfalls
|
||||
|
||||
## Section 5: Future Trends
|
||||
- Emerging technologies
|
||||
- Predicted developments
|
||||
- Opportunities and challenges
|
||||
|
||||
## Conclusion
|
||||
- Summary of key points
|
||||
- Actionable takeaways
|
||||
- Call to action
|
||||
|
||||
Multi-Perspective Content
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Generate content that presents multiple viewpoints:
|
||||
|
||||
1. **Configure Perspective Settings**:
|
||||
|
||||
* Select "Multi-Perspective" mode
|
||||
* Define the perspectives to include
|
||||
* Set balance between perspectives
|
||||
|
||||
2. **Generate Balanced Content**:
|
||||
|
||||
* AI creates content with multiple viewpoints
|
||||
* Each perspective is fairly represented
|
||||
* Supporting evidence for each view
|
||||
|
||||
3. **Review and Refine**:
|
||||
|
||||
* Check for bias in presentation
|
||||
* Ensure fair treatment of all perspectives
|
||||
* Add additional nuance if needed
|
||||
|
||||
Advanced Tone and Style Control
|
||||
-----------------------------
|
||||
|
||||
Fine-Tuning Content Voice
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Precisely control the voice of your content:
|
||||
|
||||
1. **Advanced Tone Settings**:
|
||||
|
||||
* Access the "Style Controls" panel
|
||||
* Adjust primary and secondary tones
|
||||
* Set tone intensity (1-10)
|
||||
|
||||
2. **Voice Customization**:
|
||||
|
||||
* Sentence length variation
|
||||
* Paragraph structure
|
||||
* Vocabulary complexity
|
||||
* Rhetorical devices
|
||||
|
||||
3. **Brand Voice Alignment**:
|
||||
|
||||
* Upload brand voice guidelines
|
||||
* Select from voice presets
|
||||
* Create custom voice profiles
|
||||
|
||||
Example tone configuration:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Example tone configuration
|
||||
tone_config = {
|
||||
"primary_tone": "authoritative",
|
||||
"secondary_tone": "conversational",
|
||||
"intensity": 7,
|
||||
"sentence_length": {
|
||||
"average": "medium",
|
||||
"variation": "high"
|
||||
},
|
||||
"vocabulary": {
|
||||
"complexity": "moderate",
|
||||
"industry_specific": True,
|
||||
"jargon_level": "low"
|
||||
},
|
||||
"rhetorical_devices": ["analogies", "questions", "data_points"]
|
||||
}
|
||||
|
||||
Audience-Targeted Content
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Create content specifically tailored to your audience:
|
||||
|
||||
1. **Audience Definition**:
|
||||
|
||||
* Create detailed audience personas
|
||||
* Specify demographics and psychographics
|
||||
* Define knowledge level and interests
|
||||
|
||||
2. **Content Adaptation**:
|
||||
|
||||
* Adjust complexity for audience
|
||||
* Include relevant examples and references
|
||||
* Address audience pain points
|
||||
|
||||
3. **Engagement Optimization**:
|
||||
|
||||
* Customize calls to action
|
||||
* Adjust persuasion techniques
|
||||
* Incorporate audience-specific language
|
||||
|
||||
Advanced SEO Optimization
|
||||
-----------------------
|
||||
|
||||
Semantic SEO Enhancement
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Optimize content for semantic search:
|
||||
|
||||
1. **Topic Cluster Mapping**:
|
||||
|
||||
* Identify primary and related topics
|
||||
* Map semantic relationships
|
||||
* Create content that covers the topic comprehensively
|
||||
|
||||
2. **Entity Optimization**:
|
||||
|
||||
* Identify key entities in your content
|
||||
* Establish entity relationships
|
||||
* Include structured data for entities
|
||||
|
||||
3. **Natural Language Optimization**:
|
||||
|
||||
* Optimize for natural language queries
|
||||
* Include question-answer pairs
|
||||
* Implement conversational content elements
|
||||
|
||||
Example entity mapping:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"main_entity": "Sustainable Gardening",
|
||||
"related_entities": [
|
||||
{
|
||||
"name": "Composting",
|
||||
"relationship": "technique",
|
||||
"properties": ["benefits", "methods", "materials"]
|
||||
},
|
||||
{
|
||||
"name": "Rainwater Harvesting",
|
||||
"relationship": "technique",
|
||||
"properties": ["systems", "benefits", "implementation"]
|
||||
},
|
||||
{
|
||||
"name": "Native Plants",
|
||||
"relationship": "component",
|
||||
"properties": ["benefits", "examples", "care"]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Competitive Content Analysis
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Create content that outperforms competitors:
|
||||
|
||||
1. **Competitor Content Audit**:
|
||||
|
||||
* Analyze top-ranking content
|
||||
* Identify content gaps
|
||||
* Determine competitive advantages
|
||||
|
||||
2. **Content Enhancement**:
|
||||
|
||||
* Add missing information
|
||||
* Improve depth and breadth
|
||||
* Enhance user experience elements
|
||||
|
||||
3. **Differentiation Strategy**:
|
||||
|
||||
* Develop unique angles
|
||||
* Add proprietary insights
|
||||
* Include better examples and case studies
|
||||
|
||||
Advanced Content Types
|
||||
-------------------
|
||||
|
||||
Interactive Content Generation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Create engaging interactive content:
|
||||
|
||||
1. **Quiz Generation**:
|
||||
|
||||
* Generate topic-relevant questions
|
||||
* Create multiple-choice options
|
||||
* Develop explanations for answers
|
||||
|
||||
2. **Interactive Calculators**:
|
||||
|
||||
* Define calculation parameters
|
||||
* Generate explanation text
|
||||
* Create result interpretations
|
||||
|
||||
3. **Decision Trees**:
|
||||
|
||||
* Map decision points
|
||||
* Generate content for each path
|
||||
* Create conditional logic
|
||||
|
||||
Example quiz generation:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Example quiz generation parameters
|
||||
quiz_params = {
|
||||
"topic": "Digital Marketing",
|
||||
"difficulty": "intermediate",
|
||||
"question_types": ["multiple_choice", "true_false"],
|
||||
"num_questions": 10,
|
||||
"include_explanations": True,
|
||||
"scoring_system": "standard"
|
||||
}
|
||||
|
||||
Multimedia Content Integration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Enhance content with multimedia elements:
|
||||
|
||||
1. **Image Generation**:
|
||||
|
||||
* Generate relevant images with AI
|
||||
* Create custom illustrations
|
||||
* Design infographics from content
|
||||
|
||||
2. **Video Script Creation**:
|
||||
|
||||
* Generate video scripts from content
|
||||
* Create storyboards
|
||||
* Develop shot lists
|
||||
|
||||
3. **Audio Content**:
|
||||
|
||||
* Generate podcast scripts
|
||||
* Create audio summaries
|
||||
* Develop voice content
|
||||
|
||||
Advanced Workflow Techniques
|
||||
-------------------------
|
||||
|
||||
Content Versioning and A/B Testing
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Create multiple versions to test effectiveness:
|
||||
|
||||
1. **Version Generation**:
|
||||
|
||||
* Create content variants
|
||||
* Vary headlines, intros, or CTAs
|
||||
* Maintain consistent core message
|
||||
|
||||
2. **A/B Test Setup**:
|
||||
|
||||
* Define test parameters
|
||||
* Set success metrics
|
||||
* Configure distribution
|
||||
|
||||
3. **Performance Analysis**:
|
||||
|
||||
* Compare version performance
|
||||
* Identify winning elements
|
||||
* Create optimized final version
|
||||
|
||||
Collaborative Content Creation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Work with teams on content:
|
||||
|
||||
1. **Role-Based Generation**:
|
||||
|
||||
* Assign specific roles to team members
|
||||
* Generate content components by role
|
||||
* Combine components into final piece
|
||||
|
||||
2. **Review and Feedback**:
|
||||
|
||||
* Share content for review
|
||||
* Collect structured feedback
|
||||
* Implement revisions
|
||||
|
||||
3. **Version Control**:
|
||||
|
||||
* Track content changes
|
||||
* Manage multiple drafts
|
||||
* Merge contributions
|
||||
|
||||
Content Repurposing
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Efficiently repurpose content across formats:
|
||||
|
||||
1. **Format Transformation**:
|
||||
|
||||
* Convert blog posts to social media
|
||||
* Transform articles into email sequences
|
||||
* Create presentations from long-form content
|
||||
|
||||
2. **Audience Adaptation**:
|
||||
|
||||
* Adjust content for different audiences
|
||||
* Modify tone and complexity
|
||||
* Update examples and references
|
||||
|
||||
3. **Channel Optimization**:
|
||||
|
||||
* Optimize for specific platforms
|
||||
* Adjust format and structure
|
||||
* Incorporate platform-specific elements
|
||||
|
||||
Example repurposing workflow:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Original Blog Post
|
||||
├── Social Media Posts
|
||||
│ ├── LinkedIn Article
|
||||
│ ├── Twitter Thread
|
||||
│ └── Instagram Carousel
|
||||
├── Email Sequence
|
||||
│ ├── Welcome Email
|
||||
│ ├── Deep Dive Emails (3)
|
||||
│ └── Call-to-Action Email
|
||||
├── Video Content
|
||||
│ ├── YouTube Script
|
||||
│ └── Short-Form Video Scripts
|
||||
└── Downloadable Asset
|
||||
├── PDF Guide
|
||||
└── Infographic
|
||||
|
||||
Advanced Analytics and Optimization
|
||||
--------------------------------
|
||||
|
||||
Content Performance Prediction
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Predict content performance before publishing:
|
||||
|
||||
1. **AI Performance Analysis**:
|
||||
|
||||
* Analyze content against success factors
|
||||
* Compare to high-performing content
|
||||
* Identify improvement opportunities
|
||||
|
||||
2. **Engagement Prediction**:
|
||||
|
||||
* Estimate reader engagement
|
||||
* Predict time on page
|
||||
* Calculate potential conversion rate
|
||||
|
||||
3. **SEO Ranking Prediction**:
|
||||
|
||||
* Analyze keyword competitiveness
|
||||
* Evaluate content completeness
|
||||
* Predict ranking potential
|
||||
|
||||
Iterative Content Optimization
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Continuously improve content performance:
|
||||
|
||||
1. **Performance Monitoring**:
|
||||
|
||||
* Track key performance metrics
|
||||
* Identify underperforming sections
|
||||
* Monitor user behavior
|
||||
|
||||
2. **AI-Driven Optimization**:
|
||||
|
||||
* Generate improvement suggestions
|
||||
* Enhance underperforming sections
|
||||
* Update with fresh information
|
||||
|
||||
3. **Periodic Refreshes**:
|
||||
|
||||
* Schedule content updates
|
||||
* Incorporate new research
|
||||
* Refresh examples and statistics
|
||||
|
||||
Conclusion
|
||||
---------
|
||||
|
||||
By mastering these advanced content generation techniques, you can create more sophisticated, targeted, and effective content with AI-Writer. Experiment with different approaches to find what works best for your specific content needs and audience.
|
||||
|
||||
Next Steps
|
||||
---------
|
||||
|
||||
* Explore [AI Agents for Content Creation](ai_agents.rst)
|
||||
* Learn about [Content Distribution Strategies](content_distribution.rst)
|
||||
* Discover [Advanced SEO Techniques](advanced_seo.rst)
|
||||
283
docs/tutorials/getting_started.rst
Normal file
283
docs/tutorials/getting_started.rst
Normal file
@@ -0,0 +1,283 @@
|
||||
Getting Started with AI-Writer
|
||||
==========================
|
||||
|
||||
This tutorial will guide you through the process of setting up and using AI-Writer for the first time. By the end, you'll be able to generate your first piece of AI-powered content.
|
||||
|
||||
Prerequisites
|
||||
------------
|
||||
|
||||
Before you begin, make sure you have the following:
|
||||
|
||||
1. **Python Environment**:
|
||||
|
||||
* Python 3.10 or higher installed
|
||||
* pip package manager
|
||||
* Virtual environment tool (optional but recommended)
|
||||
|
||||
2. **System Dependencies**:
|
||||
|
||||
* Windows: Microsoft Visual C++ Build Tools
|
||||
* Linux: build-essential and python3-dev packages
|
||||
* Rust compiler (for certain dependencies)
|
||||
|
||||
3. **API Keys** (optional for some features):
|
||||
|
||||
* OpenAI API key
|
||||
* Google API key (for Gemini)
|
||||
* Tavily API key (for web research)
|
||||
* Stability AI key (for image generation)
|
||||
|
||||
Installation
|
||||
-----------
|
||||
|
||||
Follow these steps to install AI-Writer:
|
||||
|
||||
1. **Clone the Repository**:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/AJaySi/AI-Writer.git
|
||||
cd AI-Writer
|
||||
|
||||
2. **Create a Virtual Environment** (optional but recommended):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Using venv
|
||||
python -m venv venv
|
||||
|
||||
# Activate on Windows
|
||||
venv\\Scripts\\activate
|
||||
|
||||
# Activate on Linux/Mac
|
||||
source venv/bin/activate
|
||||
|
||||
3. **Install Dependencies**:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install -r requirements.txt
|
||||
|
||||
4. **Check System Dependencies**:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python install_dependencies.py
|
||||
|
||||
5. **Launch the Application**:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
streamlit run alwrity.py
|
||||
|
||||
The application should now be running at http://localhost:8501.
|
||||
|
||||
Configuration
|
||||
------------
|
||||
|
||||
Before using AI-Writer, you'll need to configure it with your preferences and API keys:
|
||||
|
||||
1. **Open the Sidebar**:
|
||||
|
||||
* Click on the ">" icon in the top-left corner of the application
|
||||
|
||||
2. **Configure API Keys**:
|
||||
|
||||
* Enter your API keys for the services you plan to use
|
||||
* API keys are stored securely in your local environment
|
||||
|
||||
3. **Set Language and Region**:
|
||||
|
||||
* Choose your preferred language and region for content generation
|
||||
* This affects the research results and content style
|
||||
|
||||
4. **Configure UI Settings**:
|
||||
|
||||
* Adjust the UI theme and layout according to your preferences
|
||||
|
||||
Your First Content Generation
|
||||
----------------------------
|
||||
|
||||
Let's create your first blog post using AI-Writer:
|
||||
|
||||
1. **Select the Blog Writer**:
|
||||
|
||||
* From the main menu, select "AI Blog Writer"
|
||||
|
||||
2. **Enter Keywords**:
|
||||
|
||||
* Type in 2-3 keywords related to your topic
|
||||
* Example: "artificial intelligence content creation"
|
||||
|
||||
3. **Configure Options**:
|
||||
|
||||
* Select blog length (Short, Medium, Long)
|
||||
* Choose whether to include web research (recommended)
|
||||
* Select your target audience
|
||||
|
||||
4. **Generate Content**:
|
||||
|
||||
* Click the "Generate Blog" button
|
||||
* Wait for the AI to research and create your content
|
||||
|
||||
5. **Review and Edit**:
|
||||
|
||||
* Review the generated content
|
||||
* Make any necessary edits or adjustments
|
||||
* Use the regenerate option for specific sections if needed
|
||||
|
||||
6. **Export Your Content**:
|
||||
|
||||
* Copy the content to your clipboard
|
||||
* Export as Markdown or HTML
|
||||
* Save to your local database
|
||||
|
||||
Example: Generating a Blog Post
|
||||
------------------------------
|
||||
|
||||
Here's a step-by-step example of generating a blog post about "sustainable gardening":
|
||||
|
||||
1. Select "AI Blog Writer" from the main menu
|
||||
|
||||
2. Enter the following information:
|
||||
|
||||
* Keywords: "sustainable gardening techniques"
|
||||
* Blog Length: Medium
|
||||
* Include Web Research: Yes
|
||||
* Target Audience: Home Gardeners
|
||||
|
||||
3. Click "Generate Blog" and wait for the process to complete
|
||||
|
||||
4. Review the generated blog, which should include:
|
||||
|
||||
* An engaging introduction
|
||||
* Several sections on sustainable gardening techniques
|
||||
* Practical tips and advice
|
||||
* A conclusion with key takeaways
|
||||
|
||||
5. Edit any sections that need improvement
|
||||
|
||||
6. Export your blog post for publishing
|
||||
|
||||
Using Web Research
|
||||
----------------
|
||||
|
||||
Web research enhances your content with factual information:
|
||||
|
||||
1. **Enable Web Research**:
|
||||
|
||||
* Make sure the "Include Web Research" option is checked
|
||||
|
||||
2. **Select Research Sources**:
|
||||
|
||||
* Choose from available research providers:
|
||||
* Google Search
|
||||
* Tavily AI
|
||||
* Exa Search
|
||||
* Custom URLs
|
||||
|
||||
3. **Adjust Research Depth**:
|
||||
|
||||
* Select how deep the research should go
|
||||
* More depth means more comprehensive but slower results
|
||||
|
||||
4. **Review Research Results**:
|
||||
|
||||
* See what sources were used in your content
|
||||
* Check the research summary for key points
|
||||
|
||||
5. **Regenerate with Different Research**:
|
||||
|
||||
* If needed, you can regenerate with different research parameters
|
||||
|
||||
Customizing Content Style
|
||||
-----------------------
|
||||
|
||||
AI-Writer allows you to customize the style of your content:
|
||||
|
||||
1. **Tone Selection**:
|
||||
|
||||
* Choose from tones like Professional, Casual, Informative, etc.
|
||||
* The tone affects the writing style and vocabulary
|
||||
|
||||
2. **Content Structure**:
|
||||
|
||||
* Select different content structures:
|
||||
* Problem-Solution
|
||||
* How-To Guide
|
||||
* Listicle
|
||||
* Comparison
|
||||
* Story-based
|
||||
|
||||
3. **Writing Style**:
|
||||
|
||||
* Adjust parameters like:
|
||||
* Sentence length
|
||||
* Paragraph density
|
||||
* Technical level
|
||||
* Use of examples
|
||||
|
||||
4. **SEO Optimization**:
|
||||
|
||||
* Enable SEO optimization for better search visibility
|
||||
* Adjust keyword density and placement
|
||||
|
||||
Troubleshooting
|
||||
--------------
|
||||
|
||||
If you encounter issues, try these solutions:
|
||||
|
||||
1. **Application Won't Start**:
|
||||
|
||||
* Check Python version (must be 3.10+)
|
||||
* Verify all dependencies are installed
|
||||
* Check for error messages in the terminal
|
||||
|
||||
2. **API Connection Issues**:
|
||||
|
||||
* Verify API keys are entered correctly
|
||||
* Check internet connection
|
||||
* Ensure API services are available
|
||||
|
||||
3. **Content Generation Fails**:
|
||||
|
||||
* Try with simpler keywords
|
||||
* Disable web research temporarily
|
||||
* Check API usage limits
|
||||
|
||||
4. **Slow Performance**:
|
||||
|
||||
* Reduce research depth
|
||||
* Generate shorter content
|
||||
* Close other resource-intensive applications
|
||||
|
||||
Next Steps
|
||||
---------
|
||||
|
||||
Now that you've created your first piece of content, here are some next steps:
|
||||
|
||||
1. **Explore Other Writers**:
|
||||
|
||||
* Try the Social Media Writer
|
||||
* Experiment with the Email Writer
|
||||
* Create a YouTube script
|
||||
|
||||
2. **Use SEO Tools**:
|
||||
|
||||
* Analyze your content for SEO
|
||||
* Generate meta descriptions
|
||||
* Create structured data
|
||||
|
||||
3. **Plan Your Content**:
|
||||
|
||||
* Use the Content Calendar feature
|
||||
* Generate content ideas for the month
|
||||
* Create a content strategy
|
||||
|
||||
4. **Learn Advanced Features**:
|
||||
|
||||
* Check out the advanced tutorials
|
||||
* Explore API integration
|
||||
* Try the AI agents feature
|
||||
|
||||
For more detailed information, refer to the [User Guide](../user_guide/index.rst) and [API Documentation](../api/index.rst).
|
||||
99
docs/tutorials/index.rst
Normal file
99
docs/tutorials/index.rst
Normal file
@@ -0,0 +1,99 @@
|
||||
Tutorials
|
||||
=========
|
||||
|
||||
Welcome to the AI-Writer tutorials section. These step-by-step guides will help you learn how to use the platform effectively, from basic content generation to advanced techniques.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Tutorials:
|
||||
|
||||
getting_started
|
||||
advanced_content_generation
|
||||
seo_optimization
|
||||
social_media_content
|
||||
email_marketing
|
||||
content_planning
|
||||
ai_agents
|
||||
api_integration
|
||||
|
||||
Beginner Tutorials
|
||||
----------------
|
||||
|
||||
If you're new to AI-Writer, start with these tutorials:
|
||||
|
||||
* :doc:`getting_started` - Set up AI-Writer and create your first content
|
||||
* :doc:`seo_optimization` - Learn how to optimize your content for search engines
|
||||
* :doc:`social_media_content` - Create engaging content for social media platforms
|
||||
|
||||
Intermediate Tutorials
|
||||
--------------------
|
||||
|
||||
Once you're familiar with the basics, try these tutorials:
|
||||
|
||||
* :doc:`advanced_content_generation` - Master advanced content creation techniques
|
||||
* :doc:`email_marketing` - Generate effective email marketing campaigns
|
||||
* :doc:`content_planning` - Plan and organize your content strategy
|
||||
|
||||
Advanced Tutorials
|
||||
---------------
|
||||
|
||||
For power users looking to maximize their AI-Writer experience:
|
||||
|
||||
* :doc:`ai_agents` - Use AI agents for specialized content creation
|
||||
* :doc:`api_integration` - Integrate AI-Writer with your existing tools and workflows
|
||||
|
||||
Quick Start Guides
|
||||
---------------
|
||||
|
||||
Short guides for specific tasks:
|
||||
|
||||
1. **Creating a Blog Post**
|
||||
|
||||
* Select "AI Blog Writer" from the main menu
|
||||
* Enter your keywords and select options
|
||||
* Click "Generate Blog" and wait for results
|
||||
* Edit and export your content
|
||||
|
||||
2. **Generating Social Media Content**
|
||||
|
||||
* Choose the social media platform
|
||||
* Enter your topic or product information
|
||||
* Select tone and style
|
||||
* Generate multiple post options
|
||||
|
||||
3. **Optimizing Content for SEO**
|
||||
|
||||
* Create your content or import existing text
|
||||
* Use the "SEO Optimizer" tool
|
||||
* Review and implement suggestions
|
||||
* Generate meta descriptions and titles
|
||||
|
||||
Video Tutorials
|
||||
------------
|
||||
|
||||
Check out our video tutorials for visual learning:
|
||||
|
||||
* [Getting Started with AI-Writer](https://www.youtube.com/watch?v=example1)
|
||||
* [Advanced Content Generation Techniques](https://www.youtube.com/watch?v=example2)
|
||||
* [SEO Optimization with AI-Writer](https://www.youtube.com/watch?v=example3)
|
||||
|
||||
Tutorial Roadmap
|
||||
--------------
|
||||
|
||||
Not sure where to start? Follow this recommended learning path:
|
||||
|
||||
1. Complete the :doc:`getting_started` tutorial
|
||||
2. Try creating content with the :doc:`seo_optimization` guide
|
||||
3. Explore social media content creation with :doc:`social_media_content`
|
||||
4. Learn advanced techniques with :doc:`advanced_content_generation`
|
||||
5. Develop your content strategy with :doc:`content_planning`
|
||||
6. Explore automation with :doc:`ai_agents` and :doc:`api_integration`
|
||||
|
||||
Need Help?
|
||||
---------
|
||||
|
||||
If you need additional assistance:
|
||||
|
||||
* Check the [FAQ](../faq.rst) for common questions
|
||||
* Visit the [Community Forum](https://community.alwrity.com)
|
||||
* Contact support at support@alwrity.com
|
||||
160
docs/usage.rst
Normal file
160
docs/usage.rst
Normal file
@@ -0,0 +1,160 @@
|
||||
Usage Guide
|
||||
===========
|
||||
|
||||
Getting Started
|
||||
--------------
|
||||
|
||||
After installing and configuring AI-Writer, you can access the application through your web browser. The application is organized into several sections:
|
||||
|
||||
1. **Dashboard**: Overview of your content and analytics
|
||||
2. **Content Creation**: Tools for generating different types of content
|
||||
3. **Research**: AI-powered research tools
|
||||
4. **Analytics**: Content performance metrics
|
||||
5. **Settings**: Configuration options
|
||||
|
||||
Basic Workflow
|
||||
-------------
|
||||
|
||||
The typical workflow for using AI-Writer consists of the following steps:
|
||||
|
||||
1. **Select Content Type**
|
||||
|
||||
Choose the type of content you want to create from the sidebar menu:
|
||||
|
||||
* LinkedIn Post
|
||||
* LinkedIn Article
|
||||
* Blog Post
|
||||
* Twitter/X Post
|
||||
* Email Template
|
||||
* SEO Content
|
||||
* And more...
|
||||
|
||||
2. **Configure Content Parameters**
|
||||
|
||||
Set the parameters for your content:
|
||||
|
||||
* Topic or title
|
||||
* Target audience
|
||||
* Tone and style
|
||||
* Length
|
||||
* Keywords (for SEO)
|
||||
* Additional context
|
||||
|
||||
3. **Generate Content**
|
||||
|
||||
Click the "Generate" button to create your content. The AI will process your request and generate content based on your parameters.
|
||||
|
||||
4. **Review and Edit**
|
||||
|
||||
Review the generated content and make any necessary edits. You can:
|
||||
|
||||
* Regenerate specific sections
|
||||
* Adjust tone or style
|
||||
* Add or remove information
|
||||
* Check facts and references
|
||||
|
||||
5. **Save and Export**
|
||||
|
||||
Save your content to the database and export it in your preferred format:
|
||||
|
||||
* Plain text
|
||||
* Markdown
|
||||
* HTML
|
||||
* PDF (if configured)
|
||||
|
||||
Feature Guides
|
||||
-------------
|
||||
|
||||
LinkedIn Content Creation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To create LinkedIn content:
|
||||
|
||||
1. Select "LinkedIn Writer" from the sidebar
|
||||
2. Choose the content type (post, article, profile, etc.)
|
||||
3. Fill in the required parameters
|
||||
4. Click "Generate"
|
||||
5. Review and edit the content
|
||||
6. Save or export for posting
|
||||
|
||||
Blog Content Creation
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For blog posts and articles:
|
||||
|
||||
1. Select "Blog Writer" from the sidebar
|
||||
2. Enter the blog topic, target audience, and keywords
|
||||
3. Choose the structure (how-to, listicle, opinion, etc.)
|
||||
4. Set the desired length and tone
|
||||
5. Click "Generate"
|
||||
6. Review, edit, and export
|
||||
|
||||
SEO Optimization
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
To optimize content for search engines:
|
||||
|
||||
1. Create your content using any of the content generators
|
||||
2. Go to the "SEO Tools" section
|
||||
3. Enter your target keywords and URL (if applicable)
|
||||
4. Run the SEO analysis
|
||||
5. Apply the suggested optimizations to your content
|
||||
|
||||
Research Assistant
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
To use the AI research assistant:
|
||||
|
||||
1. Go to the "Research" section
|
||||
2. Enter your research topic or question
|
||||
3. Select research sources (web, academic, news, etc.)
|
||||
4. Set the depth and breadth of research
|
||||
5. Click "Research"
|
||||
6. Review the findings and save or export the research summary
|
||||
|
||||
Analytics Dashboard
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
To analyze your content performance:
|
||||
|
||||
1. Navigate to the "Analytics" section
|
||||
2. View overall metrics or select specific content
|
||||
3. Analyze performance by content type, date range, or other filters
|
||||
4. Export reports as needed
|
||||
|
||||
Advanced Features
|
||||
---------------
|
||||
|
||||
Custom Templates
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
You can create and save custom templates for frequently used content types:
|
||||
|
||||
1. Go to "Settings" > "Templates"
|
||||
2. Click "Create New Template"
|
||||
3. Configure the template parameters
|
||||
4. Save the template
|
||||
5. Access your templates from the content creation screens
|
||||
|
||||
Batch Processing
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
For generating multiple content pieces at once:
|
||||
|
||||
1. Go to "Batch Processing" in the sidebar
|
||||
2. Upload a CSV file with content parameters
|
||||
3. Configure batch settings
|
||||
4. Start the batch process
|
||||
5. Download the results when complete
|
||||
|
||||
API Integration
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
AI-Writer provides API endpoints for integration with other tools:
|
||||
|
||||
1. Go to "Settings" > "API"
|
||||
2. Generate an API key
|
||||
3. View the API documentation
|
||||
4. Use the provided endpoints in your applications
|
||||
|
||||
For detailed API documentation, see the :ref:`API Reference <api-reference>` section.
|
||||
@@ -138,7 +138,7 @@ def do_web_research():
|
||||
placeholder="Enter your Serper API key",
|
||||
help="Get your key at https://serper.dev"
|
||||
)
|
||||
test_key = st.checkbox("Test API key before saving", value=False, help="Validate the API key before saving")
|
||||
test_key = st.checkbox("Test API key before saving", value=False, help="Validate the API key before saving", key="test_serper_key")
|
||||
with serper_col2:
|
||||
if st.button("Save Serper", use_container_width=True):
|
||||
if serper_key:
|
||||
@@ -183,7 +183,7 @@ def do_web_research():
|
||||
placeholder="Enter your Metaphor API key",
|
||||
help="Get your key at https://metaphor.systems"
|
||||
)
|
||||
test_metaphor = st.checkbox("Test API key before saving", value=False, help="Validate the API key before saving")
|
||||
test_metaphor = st.checkbox("Test API key before saving", value=False, help="Validate the API key before saving", key="test_metaphor_key")
|
||||
with metaphor_col2:
|
||||
if st.button("Save Metaphor", use_container_width=True):
|
||||
if metaphor_key:
|
||||
@@ -227,7 +227,7 @@ def do_web_research():
|
||||
placeholder="Enter your Tavily API key",
|
||||
help="Get your key at https://tavily.com"
|
||||
)
|
||||
test_tavily = st.checkbox("Test API key before saving", value=False, help="Validate the API key before saving")
|
||||
test_tavily = st.checkbox("Test API key before saving", value=False, help="Validate the API key before saving", key="test_tavily_key")
|
||||
with tavily_col2:
|
||||
if st.button("Save Tavily", use_container_width=True):
|
||||
if tavily_key:
|
||||
@@ -271,7 +271,7 @@ def do_web_research():
|
||||
placeholder="Enter your Firecrawl API key",
|
||||
help="Get your key at https://firecrawl.co"
|
||||
)
|
||||
test_firecrawl = st.checkbox("Test API key before saving", value=False, help="Validate the API key before saving")
|
||||
test_firecrawl = st.checkbox("Test API key before saving", value=False, help="Validate the API key before saving", key="test_firecrawl_key")
|
||||
with firecrawl_col2:
|
||||
if st.button("Save Firecrawl", use_container_width=True):
|
||||
if firecrawl_key:
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
import streamlit as st
|
||||
from loguru import logger
|
||||
import os
|
||||
from typing import Dict, Any
|
||||
from ..manager import APIKeyManager
|
||||
from .base import render_navigation_buttons, render_step_indicator, render_tab_style
|
||||
@@ -161,6 +162,15 @@ def render_alwrity_integrations(api_key_manager: APIKeyManager) -> Dict[str, Any
|
||||
}
|
||||
}
|
||||
|
||||
# Set INTEGRATION_DONE to True in .env file and environment
|
||||
try:
|
||||
with open('.env', 'a') as f:
|
||||
f.write("\nINTEGRATION_DONE=True")
|
||||
os.environ['INTEGRATION_DONE'] = "True"
|
||||
logger.info("Set INTEGRATION_DONE=True in .env and environment")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to set INTEGRATION_DONE: {str(e)}")
|
||||
|
||||
# Update progress and move to next step
|
||||
st.session_state['current_step'] = 6
|
||||
st.rerun()
|
||||
|
||||
@@ -62,10 +62,11 @@ def render_step_indicator(current_step: int, total_steps: int) -> None:
|
||||
|
||||
steps = [
|
||||
("🔑", "AI LLM", 1),
|
||||
("👤", "AI Research", 2),
|
||||
("🎨", "Personalization", 3),
|
||||
("🔄", "Integrations", 4),
|
||||
("✅", "Complete", 5)
|
||||
("🔍", "Website Analysis", 2),
|
||||
("👤", "AI Research", 3),
|
||||
("🎨", "Personalization", 4),
|
||||
("🔄", "Integrations", 5),
|
||||
("✅", "Complete", 6)
|
||||
]
|
||||
|
||||
html = '<div class="step-indicator">'
|
||||
|
||||
@@ -45,37 +45,139 @@ def render_final_setup(api_key_manager: APIKeyManager) -> Dict[str, Any]:
|
||||
"""
|
||||
logger.info("[render_final_setup] Rendering final setup component")
|
||||
|
||||
st.markdown("### Step 5: Final Setup")
|
||||
st.markdown("### Step 6: Final Setup & Validation")
|
||||
|
||||
# Load main config
|
||||
main_config = load_main_config()
|
||||
|
||||
# Display configuration summary
|
||||
st.markdown("#### Configuration Summary")
|
||||
# Create tabs for each step
|
||||
tabs = st.tabs([
|
||||
"Step 1: AI LLM Setup",
|
||||
"Step 2: Website Analysis",
|
||||
"Step 3: AI Research",
|
||||
"Step 4: Personalization",
|
||||
"Step 5: Integrations"
|
||||
])
|
||||
|
||||
# Blog Content Characteristics
|
||||
st.markdown("##### Blog Content Characteristics")
|
||||
blog_settings = main_config.get("Blog Content Characteristics", {})
|
||||
st.write(f"- Blog Length: {blog_settings.get('Blog Length', '2000')}")
|
||||
st.write(f"- Blog Tone: {blog_settings.get('Blog Tone', 'Professional')}")
|
||||
st.write(f"- Blog Demographic: {blog_settings.get('Blog Demographic', 'Professional')}")
|
||||
st.write(f"- Blog Type: {blog_settings.get('Blog Type', 'Informational')}")
|
||||
# Step 1: AI LLM Setup
|
||||
with tabs[0]:
|
||||
st.markdown("#### AI LLM Configuration")
|
||||
|
||||
# Get API keys from environment
|
||||
openai_key = os.getenv('OPENAI_API_KEY', 'Not configured')
|
||||
gemini_key = os.getenv('GEMINI_API_KEY', 'Not configured')
|
||||
anthropic_key = os.getenv('ANTHROPIC_API_KEY', 'Not configured')
|
||||
mistral_key = os.getenv('MISTRAL_API_KEY', 'Not configured')
|
||||
|
||||
# Display API keys (masked)
|
||||
st.markdown("##### API Keys")
|
||||
col1, col2 = st.columns(2)
|
||||
|
||||
with col1:
|
||||
st.markdown(f"**OpenAI API Key:** {'*' * 8}{openai_key[-4:] if openai_key != 'Not configured' else ''}")
|
||||
st.markdown(f"**Google Gemini API Key:** {'*' * 8}{gemini_key[-4:] if gemini_key != 'Not configured' else ''}")
|
||||
|
||||
with col2:
|
||||
st.markdown(f"**Anthropic API Key:** {'*' * 8}{anthropic_key[-4:] if anthropic_key != 'Not configured' else ''}")
|
||||
st.markdown(f"**Mistral API Key:** {'*' * 8}{mistral_key[-4:] if mistral_key != 'Not configured' else ''}")
|
||||
|
||||
# LLM Options
|
||||
st.markdown("##### LLM Options")
|
||||
llm_settings = main_config.get("LLM Options", {})
|
||||
st.write(f"- GPT Provider: {llm_settings.get('GPT Provider', 'google')}")
|
||||
st.write(f"- Model: {llm_settings.get('Model', 'gemini-1.5-flash-latest')}")
|
||||
st.write(f"- Temperature: {llm_settings.get('Temperature', 0.7)}")
|
||||
st.write(f"- Max Tokens: {llm_settings.get('Max Tokens', 4000)}")
|
||||
# Step 2: Website Analysis
|
||||
with tabs[1]:
|
||||
st.markdown("#### Website Analysis Configuration")
|
||||
|
||||
# Get website URL from environment
|
||||
website_url = os.getenv('WEBSITE_URL', 'Not configured')
|
||||
|
||||
# Display website URL
|
||||
st.markdown("##### Website URL")
|
||||
st.markdown(f"**Website URL:** {website_url}")
|
||||
|
||||
# Display website analysis settings
|
||||
st.markdown("##### Analysis Settings")
|
||||
st.markdown("Website analysis settings will be used to understand your content style and preferences.")
|
||||
|
||||
# Personalization Settings
|
||||
st.markdown("##### Personalization Settings")
|
||||
personalization = main_config.get("personalization", {})
|
||||
st.write(f"- Writing Tone: {personalization.get('writing_tone', 'Professional')}")
|
||||
st.write(f"- Target Audience: {personalization.get('target_audience', 'General')}")
|
||||
st.write(f"- Content Type: {personalization.get('content_type', 'Blog Posts')}")
|
||||
# Step 3: AI Research
|
||||
with tabs[2]:
|
||||
st.markdown("#### AI Research Configuration")
|
||||
|
||||
# Get research API keys from environment
|
||||
serpapi_key = os.getenv('SERPAPI_KEY', 'Not configured')
|
||||
tavily_key = os.getenv('TAVILY_API_KEY', 'Not configured')
|
||||
metaphor_key = os.getenv('METAPHOR_API_KEY', 'Not configured')
|
||||
firecrawl_key = os.getenv('FIRECRAWL_API_KEY', 'Not configured')
|
||||
|
||||
# Display API keys (masked)
|
||||
st.markdown("##### Research API Keys")
|
||||
col1, col2 = st.columns(2)
|
||||
|
||||
with col1:
|
||||
st.markdown(f"**SerpAPI Key:** {'*' * 8}{serpapi_key[-4:] if serpapi_key != 'Not configured' else ''}")
|
||||
st.markdown(f"**Tavily API Key:** {'*' * 8}{tavily_key[-4:] if tavily_key != 'Not configured' else ''}")
|
||||
|
||||
with col2:
|
||||
st.markdown(f"**Metaphor API Key:** {'*' * 8}{metaphor_key[-4:] if metaphor_key != 'Not configured' else ''}")
|
||||
st.markdown(f"**Firecrawl API Key:** {'*' * 8}{firecrawl_key[-4:] if firecrawl_key != 'Not configured' else ''}")
|
||||
|
||||
# Step 4: Personalization
|
||||
with tabs[3]:
|
||||
st.markdown("#### Personalization Configuration")
|
||||
|
||||
# Display personalization settings from main config
|
||||
with st.popover("Blog Content Characteristics", help="Click to see details about blog content settings"):
|
||||
st.markdown("##### Blog Content Characteristics")
|
||||
blog_settings = main_config.get("Blog Content Characteristics", {})
|
||||
st.write(f"- Blog Length: {blog_settings.get('Blog Length', '2000')}")
|
||||
st.write(f"- Blog Tone: {blog_settings.get('Blog Tone', 'Professional')}")
|
||||
st.write(f"- Blog Demographic: {blog_settings.get('Blog Demographic', 'Professional')}")
|
||||
st.write(f"- Blog Type: {blog_settings.get('Blog Type', 'Informational')}")
|
||||
st.write(f"- Blog Language: {blog_settings.get('Blog Language', 'English')}")
|
||||
st.write(f"- Blog Output Format: {blog_settings.get('Blog Output Format', 'markdown')}")
|
||||
st.markdown("These settings define the overall structure and style of your blog content.")
|
||||
|
||||
with st.popover("Blog Images Details", help="Click to see details about image generation settings"):
|
||||
st.markdown("##### Blog Images Details")
|
||||
image_settings = main_config.get("Blog Images Details", {})
|
||||
st.write(f"- Image Generation Model: {image_settings.get('Image Generation Model', 'stable-diffusion')}")
|
||||
st.write(f"- Number of Blog Images: {image_settings.get('Number of Blog Images', 1)}")
|
||||
st.markdown("These settings control how images are generated for your blog posts.")
|
||||
|
||||
with st.popover("LLM Options", help="Click to see details about language model settings"):
|
||||
st.markdown("##### LLM Options")
|
||||
llm_settings = main_config.get("LLM Options", {})
|
||||
st.write(f"- GPT Provider: {llm_settings.get('GPT Provider', 'google')}")
|
||||
st.write(f"- Model: {llm_settings.get('Model', 'gemini-1.5-flash-latest')}")
|
||||
st.write(f"- Temperature: {llm_settings.get('Temperature', 0.7)}")
|
||||
st.write(f"- Top-p: {llm_settings.get('Top-p', 0.9)}")
|
||||
st.write(f"- Max Tokens: {llm_settings.get('Max Tokens', 4000)}")
|
||||
st.write(f"- Frequency Penalty: {llm_settings.get('Frequency Penalty', 1.0)}")
|
||||
st.write(f"- Presence Penalty: {llm_settings.get('Presence Penalty', 1.0)}")
|
||||
st.markdown("These settings control the behavior of the language model used for content generation.")
|
||||
|
||||
with st.popover("Search Engine Parameters", help="Click to see details about search engine settings"):
|
||||
st.markdown("##### Search Engine Parameters")
|
||||
search_settings = main_config.get("Search Engine Parameters", {})
|
||||
st.write(f"- Geographic Location: {search_settings.get('Geographic Location', 'us')}")
|
||||
st.write(f"- Search Language: {search_settings.get('Search Language', 'en')}")
|
||||
st.write(f"- Number of Results: {search_settings.get('Number of Results', 10)}")
|
||||
st.write(f"- Time Range: {search_settings.get('Time Range', 'anytime')}")
|
||||
st.markdown("These settings control how search engines are used for research and content creation.")
|
||||
|
||||
# Step 5: Integrations
|
||||
with tabs[4]:
|
||||
st.markdown("#### ALwrity Integrations Configuration")
|
||||
|
||||
# Display integrations settings
|
||||
st.markdown("##### Website Platforms")
|
||||
st.info("WordPress integration will be available in the next update")
|
||||
st.info("Wix integration will be available in the next update")
|
||||
|
||||
st.markdown("##### Social Media")
|
||||
st.info("Facebook integration will be available in the next update")
|
||||
st.info("Instagram integration will be available in the next update")
|
||||
|
||||
st.markdown("##### Analytics Tools")
|
||||
st.info("Google Search Console integration will be available in the next update")
|
||||
|
||||
# Navigation buttons
|
||||
col1, col2 = st.columns(2)
|
||||
|
||||
@@ -90,37 +192,37 @@ def render_final_setup(api_key_manager: APIKeyManager) -> Dict[str, Any]:
|
||||
if st.button("Complete Setup →"):
|
||||
logger.info("[render_final_setup] User clicked complete setup")
|
||||
try:
|
||||
# Verify all required API keys are present and valid
|
||||
is_valid = check_all_api_keys(api_key_manager)
|
||||
# Log the current API keys in the manager
|
||||
logger.info("[render_final_setup] Current API keys in manager:")
|
||||
for key, value in api_key_manager.api_keys.items():
|
||||
if value:
|
||||
logger.info(f" - {key}: {'*' * 8}{value[-4:]}")
|
||||
else:
|
||||
logger.info(f" - {key}: Not set")
|
||||
|
||||
if not is_valid:
|
||||
st.error("⚠️ Some required API keys are missing")
|
||||
st.markdown("### Missing API Keys and Impact")
|
||||
|
||||
# Display impact messages
|
||||
st.warning("⚠️ Missing AI Provider: At least one AI provider (OpenAI, Google Gemini, Anthropic Claude, or Mistral) is required.")
|
||||
st.warning("⚠️ Missing Research Provider: At least one research provider (SerpAPI, Tavily, Metaphor, or Firecrawl) is required.")
|
||||
|
||||
st.markdown("""
|
||||
<div style='background-color: #fff3cd; color: #856404; padding: 1rem; border-radius: 0.25rem; margin-top: 1rem;'>
|
||||
<h4 style='margin: 0;'>Required Keys:</h4>
|
||||
<ul style='margin: 0.5rem 0 0;'>
|
||||
<li>At least one AI provider (OpenAI, Google Gemini, Anthropic Claude, or Mistral)</li>
|
||||
<li>At least one research provider (SerpAPI, Tavily, Metaphor, or Firecrawl)</li>
|
||||
</ul>
|
||||
<p style='margin: 0.5rem 0 0;'>Please configure the required keys before proceeding.</p>
|
||||
</div>
|
||||
""", unsafe_allow_html=True)
|
||||
return {"current_step": 6, "changes_made": True}
|
||||
# Log environment variables
|
||||
logger.info("[render_final_setup] Checking environment variables:")
|
||||
for key in os.environ.keys():
|
||||
if any(provider in key for provider in ['API_KEY', 'SERPAPI', 'TAVILY', 'METAPHOR', 'FIRECRAWL']):
|
||||
value = os.getenv(key)
|
||||
if value:
|
||||
logger.info(f" - {key}: {'*' * 8}{value[-4:]}")
|
||||
else:
|
||||
logger.error(f" - {key}: Not set")
|
||||
|
||||
# Save final configuration
|
||||
if not os.path.exists("lib/workspace/alwrity_config"):
|
||||
os.makedirs("lib/workspace/alwrity_config")
|
||||
|
||||
config_path = os.path.join("lib", "workspace", "alwrity_config", "main_config.json")
|
||||
with open(config_path, 'w') as f:
|
||||
json.dump(main_config, f, indent=4)
|
||||
|
||||
# Set FINAL_SETUP_COMPLETE to True in .env file and environment
|
||||
try:
|
||||
with open('.env', 'a') as f:
|
||||
f.write("\nFINAL_SETUP_COMPLETE=True")
|
||||
os.environ['FINAL_SETUP_COMPLETE'] = "True"
|
||||
logger.info("Set FINAL_SETUP_COMPLETE=True in .env and environment")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to set FINAL_SETUP_COMPLETE: {str(e)}")
|
||||
|
||||
# Show success message with HTML formatting
|
||||
st.markdown("""
|
||||
<div style='background-color: #d4edda; color: #155724; padding: 1rem; border-radius: 0.25rem;'>
|
||||
@@ -133,11 +235,11 @@ def render_final_setup(api_key_manager: APIKeyManager) -> Dict[str, Any]:
|
||||
st.session_state['setup_completed'] = True
|
||||
|
||||
# Redirect to main application
|
||||
st.switch_page("alwrity.py")
|
||||
st.rerun()
|
||||
|
||||
except Exception as e:
|
||||
error_msg = f"Error completing setup: {str(e)}"
|
||||
logger.error(f"[render_final_setup] {error_msg}")
|
||||
st.error(error_msg)
|
||||
|
||||
return {"current_step": 5, "changes_made": True}
|
||||
return {"current_step": 6, "changes_made": True}
|
||||
@@ -4,6 +4,7 @@ import streamlit as st
|
||||
from loguru import logger
|
||||
import sys
|
||||
import json
|
||||
import os
|
||||
from typing import Dict, Any
|
||||
from ..manager import APIKeyManager
|
||||
from ....web_crawlers.async_web_crawler import AsyncWebCrawlerService
|
||||
@@ -495,6 +496,15 @@ def render_personalization_setup(api_key_manager: APIKeyManager) -> Dict[str, An
|
||||
}
|
||||
|
||||
if save_main_config(main_config):
|
||||
# Set PERSONALIZATION_DONE to True in .env file and environment
|
||||
try:
|
||||
with open('.env', 'a') as f:
|
||||
f.write("\nPERSONALIZATION_DONE=True")
|
||||
os.environ['PERSONALIZATION_DONE'] = "True"
|
||||
logger.info("Set PERSONALIZATION_DONE=True in .env and environment")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to set PERSONALIZATION_DONE: {str(e)}")
|
||||
|
||||
st.success("✅ Your personalization settings have been saved successfully!")
|
||||
else:
|
||||
st.error("Unable to save settings. Please try again.")
|
||||
@@ -702,8 +712,20 @@ def render_personalization_setup(api_key_manager: APIKeyManager) -> Dict[str, An
|
||||
st.success("Configuration saved successfully!")
|
||||
|
||||
# Navigation buttons with correct arguments
|
||||
if render_navigation_buttons(3, 4, changes_made=True):
|
||||
st.session_state.current_step = 4
|
||||
if render_navigation_buttons(4, 6, changes_made=True):
|
||||
# Set PERSONALIZATION_DONE to False if not already set to True
|
||||
if 'PERSONALIZATION_DONE' not in os.environ or os.environ['PERSONALIZATION_DONE'] != "True":
|
||||
try:
|
||||
with open('.env', 'a') as f:
|
||||
f.write("\nPERSONALIZATION_DONE=False")
|
||||
os.environ['PERSONALIZATION_DONE'] = "False"
|
||||
logger.info("Set PERSONALIZATION_DONE=False in .env and environment")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to set PERSONALIZATION_DONE: {str(e)}")
|
||||
|
||||
# Update the current step to 5 (ALwrity integrations)
|
||||
st.session_state.current_step = 5
|
||||
logger.info("Moving to step 5: ALwrity integrations")
|
||||
st.rerun()
|
||||
|
||||
return {"current_step": 3, "changes_made": True}
|
||||
return {"current_step": 4, "changes_made": True}
|
||||
@@ -9,6 +9,7 @@ import sys
|
||||
from typing import Dict, Any
|
||||
from ..manager import APIKeyManager
|
||||
from .base import render_navigation_buttons
|
||||
import os
|
||||
|
||||
# Configure logger to output to both file and stdout
|
||||
logger.remove() # Remove default handler
|
||||
@@ -45,6 +46,24 @@ def render_website_setup(api_key_manager: APIKeyManager) -> Dict[str, Any]:
|
||||
url = st.text_input("Enter your website URL, if you own one", placeholder="https://example.com")
|
||||
logger.info(f"[render_website_setup] URL input value: {url}")
|
||||
|
||||
# Save URL to .env file
|
||||
try:
|
||||
if url:
|
||||
# Save to .env file
|
||||
with open('.env', 'a') as f:
|
||||
f.write(f"\nWEBSITE_URL={url}")
|
||||
# Set environment variable
|
||||
os.environ['WEBSITE_URL'] = url
|
||||
logger.info(f"[render_website_setup] Saved website URL to .env: {url}")
|
||||
else:
|
||||
# Set default value if no URL provided
|
||||
with open('.env', 'a') as f:
|
||||
f.write("\nWEBSITE_URL=no_website_provided")
|
||||
os.environ['WEBSITE_URL'] = "no_website_provided"
|
||||
logger.info("[render_website_setup] Set default website URL: no_website_provided")
|
||||
except Exception as e:
|
||||
logger.error(f"[render_website_setup] Failed to save website URL: {str(e)}")
|
||||
|
||||
analyze_type = st.radio(
|
||||
"Analysis Type",
|
||||
["Basic Website Analysis", "Full Website Analysis with SEO"],
|
||||
|
||||
@@ -119,17 +119,48 @@ class APIKeyManager:
|
||||
|
||||
def load_api_keys(self):
|
||||
"""Load API keys from environment variables."""
|
||||
logger.info("[APIKeyManager.load_api_keys] Loading API keys from environment")
|
||||
try:
|
||||
# Load from environment variables
|
||||
self.api_keys = {
|
||||
"openai": os.getenv("OPENAI_API_KEY", ""),
|
||||
"google": os.getenv("GOOGLE_API_KEY", ""),
|
||||
"tavily": os.getenv("TAVILY_API_KEY", ""),
|
||||
"metaphor": os.getenv("METAPHOR_API_KEY", ""),
|
||||
"mistral": os.getenv("MISTRAL_API_KEY", "")
|
||||
}
|
||||
logger.info("[APIKeyManager.load_api_keys] Successfully loaded API keys")
|
||||
logger.info("[APIKeyManager.load_api_keys] Loading API keys from environment")
|
||||
|
||||
# Get the current working directory and .env file path
|
||||
current_dir = os.getcwd()
|
||||
env_path = os.path.join(current_dir, '.env')
|
||||
logger.info(f"[APIKeyManager.load_api_keys] Looking for .env file at: {env_path}")
|
||||
|
||||
# Check if .env file exists
|
||||
if not os.path.exists(env_path):
|
||||
logger.warning(f"[APIKeyManager.load_api_keys] .env file not found at {env_path}")
|
||||
return
|
||||
|
||||
# Load environment variables
|
||||
load_dotenv(env_path, override=True)
|
||||
logger.debug("[APIKeyManager.load_api_keys] Environment variables loaded")
|
||||
|
||||
# Define all possible API key providers
|
||||
all_providers = [
|
||||
# AI Providers
|
||||
'OPENAI_API_KEY',
|
||||
'GEMINI_API_KEY',
|
||||
'ANTHROPIC_API_KEY',
|
||||
'MISTRAL_API_KEY',
|
||||
# Research Providers
|
||||
'SERPAPI_KEY',
|
||||
'TAVILY_API_KEY',
|
||||
'METAPHOR_API_KEY',
|
||||
'FIRECRAWL_API_KEY'
|
||||
]
|
||||
|
||||
# Load API keys from environment variables
|
||||
for provider in all_providers:
|
||||
value = os.getenv(provider)
|
||||
if value:
|
||||
self.api_keys[provider] = value
|
||||
logger.info(f"[APIKeyManager.load_api_keys] Loaded {provider} from environment")
|
||||
else:
|
||||
logger.debug(f"[APIKeyManager.load_api_keys] {provider} not found in environment")
|
||||
|
||||
logger.info(f"[APIKeyManager.load_api_keys] Loaded {len(self.api_keys)} API keys")
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"[APIKeyManager.load_api_keys] Error loading API keys: {str(e)}")
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ def check_all_api_keys(api_key_manager: APIKeyManager) -> bool:
|
||||
return False
|
||||
|
||||
# Load environment variables
|
||||
load_dotenv(env_path)
|
||||
load_dotenv(env_path, override=True) # Add override=True to ensure variables are reloaded
|
||||
logger.debug("Environment variables loaded")
|
||||
|
||||
# Log all environment variables (without their values)
|
||||
@@ -59,7 +59,17 @@ def check_all_api_keys(api_key_manager: APIKeyManager) -> bool:
|
||||
has_ai_provider = any(os.getenv(key) for key in ai_providers)
|
||||
if not has_ai_provider:
|
||||
logger.warning("No AI provider API key found")
|
||||
return False
|
||||
# Check if keys are in the API key manager
|
||||
if hasattr(api_key_manager, 'get_api_key'):
|
||||
for provider in ai_providers:
|
||||
key = api_key_manager.get_api_key(provider)
|
||||
if key:
|
||||
logger.info(f"Found {provider} in API key manager")
|
||||
has_ai_provider = True
|
||||
break
|
||||
|
||||
if not has_ai_provider:
|
||||
return False
|
||||
else:
|
||||
logger.success("✓ At least one AI provider key found")
|
||||
|
||||
@@ -83,11 +93,59 @@ def check_all_api_keys(api_key_manager: APIKeyManager) -> bool:
|
||||
has_research_provider = any(os.getenv(key) for key in research_providers)
|
||||
if not has_research_provider:
|
||||
logger.warning("No research provider API key found")
|
||||
return False
|
||||
# Check if keys are in the API key manager
|
||||
if hasattr(api_key_manager, 'get_api_key'):
|
||||
for provider in research_providers:
|
||||
key = api_key_manager.get_api_key(provider)
|
||||
if key:
|
||||
logger.info(f"Found {provider} in API key manager")
|
||||
has_research_provider = True
|
||||
break
|
||||
|
||||
if not has_research_provider:
|
||||
return False
|
||||
else:
|
||||
logger.success("✓ At least one research provider key found")
|
||||
|
||||
logger.success("All required API keys validated successfully!")
|
||||
# Step 3: Check for website URL
|
||||
logger.info("Checking website URL...")
|
||||
website_url = os.getenv('WEBSITE_URL')
|
||||
if not website_url:
|
||||
logger.warning("No website URL found in environment variables")
|
||||
return False
|
||||
else:
|
||||
logger.success(f"✓ Website URL found: {website_url}")
|
||||
|
||||
# Step 4: Check for personalization status
|
||||
logger.info("Checking personalization status...")
|
||||
if 'PERSONALIZATION_DONE' not in os.environ:
|
||||
logger.warning("PERSONALIZATION_DONE environment variable is not defined")
|
||||
return False
|
||||
else:
|
||||
logger.success(f"✓ Personalization status: {os.environ['PERSONALIZATION_DONE']}")
|
||||
|
||||
# Step 5: Check for integration status
|
||||
logger.info("Checking integration status...")
|
||||
if 'INTEGRATION_DONE' not in os.environ:
|
||||
logger.warning("INTEGRATION_DONE environment variable is not defined")
|
||||
return False
|
||||
else:
|
||||
logger.success(f"✓ Integration status: {os.environ['INTEGRATION_DONE']}")
|
||||
|
||||
# Step 6: Check for final setup status
|
||||
logger.info("Checking final setup status...")
|
||||
if 'FINAL_SETUP_COMPLETE' not in os.environ:
|
||||
logger.warning("FINAL_SETUP_COMPLETE environment variable is not defined")
|
||||
return False
|
||||
else:
|
||||
final_setup_status = os.environ['FINAL_SETUP_COMPLETE']
|
||||
if final_setup_status.lower() == 'true':
|
||||
logger.success("✓ Final setup completed successfully")
|
||||
else:
|
||||
logger.warning("Final setup validation failed")
|
||||
return False
|
||||
|
||||
logger.success("All required API keys and setup steps validated successfully!")
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
|
||||
@@ -17,7 +17,6 @@
|
||||
"Temperature": 0.7,
|
||||
"Top-p": 0.9,
|
||||
"Max Tokens": 4000,
|
||||
"N": 1,
|
||||
"Frequency Penalty": 1.0,
|
||||
"Presence Penalty": 1.0
|
||||
},
|
||||
@@ -25,8 +24,6 @@
|
||||
"Geographic Location": "us",
|
||||
"Search Language": "en",
|
||||
"Number of Results": 10,
|
||||
"Time Range": "anytime",
|
||||
"Include Domains": "",
|
||||
"Similar URL": ""
|
||||
"Time Range": "anytime"
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user