diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -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) diff --git a/docs/api/ai_writers.rst b/docs/api/ai_writers.rst new file mode 100644 index 00000000..dcc5e25f --- /dev/null +++ b/docs/api/ai_writers.rst @@ -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: \ No newline at end of file diff --git a/docs/api/analytics.rst b/docs/api/analytics.rst new file mode 100644 index 00000000..3de96983 --- /dev/null +++ b/docs/api/analytics.rst @@ -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: \ No newline at end of file diff --git a/docs/api/core.rst b/docs/api/core.rst new file mode 100644 index 00000000..fb490b6d --- /dev/null +++ b/docs/api/core.rst @@ -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: \ No newline at end of file diff --git a/docs/api/database.rst b/docs/api/database.rst new file mode 100644 index 00000000..d89eb8c7 --- /dev/null +++ b/docs/api/database.rst @@ -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: \ No newline at end of file diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 00000000..56d387e2 --- /dev/null +++ b/docs/api/index.rst @@ -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 \ No newline at end of file diff --git a/docs/api/utils.rst b/docs/api/utils.rst new file mode 100644 index 00000000..fafc02da --- /dev/null +++ b/docs/api/utils.rst @@ -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: \ No newline at end of file diff --git a/docs/api/web_crawlers.rst b/docs/api/web_crawlers.rst new file mode 100644 index 00000000..4a10ca33 --- /dev/null +++ b/docs/api/web_crawlers.rst @@ -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: \ No newline at end of file diff --git a/docs/architecture/api_design.rst b/docs/architecture/api_design.rst new file mode 100644 index 00000000..9f148e85 --- /dev/null +++ b/docs/architecture/api_design.rst @@ -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 \ No newline at end of file diff --git a/docs/architecture/architecture_overview.rst b/docs/architecture/architecture_overview.rst new file mode 100644 index 00000000..4811371a --- /dev/null +++ b/docs/architecture/architecture_overview.rst @@ -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 \ No newline at end of file diff --git a/docs/architecture/component_diagram.rst b/docs/architecture/component_diagram.rst new file mode 100644 index 00000000..71e8a377 --- /dev/null +++ b/docs/architecture/component_diagram.rst @@ -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 \ No newline at end of file diff --git a/docs/architecture/database_schema.rst b/docs/architecture/database_schema.rst new file mode 100644 index 00000000..bbe346fb --- /dev/null +++ b/docs/architecture/database_schema.rst @@ -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 \ No newline at end of file diff --git a/docs/architecture/deployment.rst b/docs/architecture/deployment.rst new file mode 100644 index 00000000..87d83158 --- /dev/null +++ b/docs/architecture/deployment.rst @@ -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 \ No newline at end of file diff --git a/docs/architecture/diagrams/content_generation_workflow.png b/docs/architecture/diagrams/content_generation_workflow.png new file mode 100644 index 00000000..27d93037 Binary files /dev/null and b/docs/architecture/diagrams/content_generation_workflow.png differ diff --git a/docs/architecture/diagrams/database_architecture.png b/docs/architecture/diagrams/database_architecture.png new file mode 100644 index 00000000..2fed6e2b Binary files /dev/null and b/docs/architecture/diagrams/database_architecture.png differ diff --git a/docs/architecture/diagrams/high_level_architecture.png b/docs/architecture/diagrams/high_level_architecture.png new file mode 100644 index 00000000..6d0ab11e Binary files /dev/null and b/docs/architecture/diagrams/high_level_architecture.png differ diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst new file mode 100644 index 00000000..6092711c --- /dev/null +++ b/docs/architecture/index.rst @@ -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 \ No newline at end of file diff --git a/docs/architecture/security.rst b/docs/architecture/security.rst new file mode 100644 index 00000000..7930522c --- /dev/null +++ b/docs/architecture/security.rst @@ -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 \ No newline at end of file diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 00000000..86eb27f8 --- /dev/null +++ b/docs/changelog.rst @@ -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 \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..dd5d06ad --- /dev/null +++ b/docs/conf.py @@ -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'] diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..d2805538 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,5 @@ +Contributing +============ + +.. include:: ../CONTRIBUTING.md + :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/docs/developer/coding_standards.rst b/docs/developer/coding_standards.rst new file mode 100644 index 00000000..730e0416 --- /dev/null +++ b/docs/developer/coding_standards.rst @@ -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___` + + 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 \ No newline at end of file diff --git a/docs/developer/index.rst b/docs/developer/index.rst new file mode 100644 index 00000000..a5243393 --- /dev/null +++ b/docs/developer/index.rst @@ -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 \ No newline at end of file diff --git a/docs/developer/setup.rst b/docs/developer/setup.rst new file mode 100644 index 00000000..455020e0 --- /dev/null +++ b/docs/developer/setup.rst @@ -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 \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..64468a17 --- /dev/null +++ b/docs/index.rst @@ -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.) + diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..14b285b9 --- /dev/null +++ b/docs/installation.rst @@ -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. \ No newline at end of file diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 00000000..a2a8a6d8 --- /dev/null +++ b/docs/introduction.rst @@ -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. \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..954237b9 --- /dev/null +++ b/docs/make.bat @@ -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 diff --git a/docs/roadmap.rst b/docs/roadmap.rst new file mode 100644 index 00000000..56b04f70 --- /dev/null +++ b/docs/roadmap.rst @@ -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. \ No newline at end of file diff --git a/docs/tutorials/advanced_content_generation.rst b/docs/tutorials/advanced_content_generation.rst new file mode 100644 index 00000000..4ffe2858 --- /dev/null +++ b/docs/tutorials/advanced_content_generation.rst @@ -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) \ No newline at end of file diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst new file mode 100644 index 00000000..adb5f137 --- /dev/null +++ b/docs/tutorials/getting_started.rst @@ -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). \ No newline at end of file diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 00000000..fef3e10f --- /dev/null +++ b/docs/tutorials/index.rst @@ -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 \ No newline at end of file diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 00000000..5be1abd9 --- /dev/null +++ b/docs/usage.rst @@ -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 ` section. \ No newline at end of file diff --git a/lib/alwrity_ui/keyword_web_researcher.py b/lib/alwrity_ui/keyword_web_researcher.py index d5294ed8..7158d985 100644 --- a/lib/alwrity_ui/keyword_web_researcher.py +++ b/lib/alwrity_ui/keyword_web_researcher.py @@ -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: diff --git a/lib/utils/api_key_manager/components/alwrity_integrations.py b/lib/utils/api_key_manager/components/alwrity_integrations.py index 981b2f21..9f11b2e1 100644 --- a/lib/utils/api_key_manager/components/alwrity_integrations.py +++ b/lib/utils/api_key_manager/components/alwrity_integrations.py @@ -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() diff --git a/lib/utils/api_key_manager/components/base.py b/lib/utils/api_key_manager/components/base.py index feff7169..1953b012 100644 --- a/lib/utils/api_key_manager/components/base.py +++ b/lib/utils/api_key_manager/components/base.py @@ -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 = '
' diff --git a/lib/utils/api_key_manager/components/final_setup.py b/lib/utils/api_key_manager/components/final_setup.py index 5dc2654a..6f7ea881 100644 --- a/lib/utils/api_key_manager/components/final_setup.py +++ b/lib/utils/api_key_manager/components/final_setup.py @@ -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(""" -
-

Required Keys:

-
    -
  • At least one AI provider (OpenAI, Google Gemini, Anthropic Claude, or Mistral)
    • -
  • At least one research provider (SerpAPI, Tavily, Metaphor, or Firecrawl)
    • -
-

Please configure the required keys before proceeding.

-
- """, 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("""
@@ -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} \ No newline at end of file diff --git a/lib/utils/api_key_manager/components/personalization_setup.py b/lib/utils/api_key_manager/components/personalization_setup.py index 7f332052..3b19ae33 100644 --- a/lib/utils/api_key_manager/components/personalization_setup.py +++ b/lib/utils/api_key_manager/components/personalization_setup.py @@ -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} \ No newline at end of file + return {"current_step": 4, "changes_made": True} \ No newline at end of file diff --git a/lib/utils/api_key_manager/components/website_setup.py b/lib/utils/api_key_manager/components/website_setup.py index f3548ff9..ff260ee7 100644 --- a/lib/utils/api_key_manager/components/website_setup.py +++ b/lib/utils/api_key_manager/components/website_setup.py @@ -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"], diff --git a/lib/utils/api_key_manager/manager.py b/lib/utils/api_key_manager/manager.py index 2897c1be..3f66fbaa 100644 --- a/lib/utils/api_key_manager/manager.py +++ b/lib/utils/api_key_manager/manager.py @@ -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)}") diff --git a/lib/utils/api_key_manager/validation.py b/lib/utils/api_key_manager/validation.py index a8dd812b..c0ef73cb 100644 --- a/lib/utils/api_key_manager/validation.py +++ b/lib/utils/api_key_manager/validation.py @@ -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: diff --git a/lib/workspace/alwrity_config/main_config.json b/lib/workspace/alwrity_config/main_config.json index 9ad590df..cbe9e4b9 100644 --- a/lib/workspace/alwrity_config/main_config.json +++ b/lib/workspace/alwrity_config/main_config.json @@ -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" } } \ No newline at end of file