Upload folder using huggingface_hub

knowledge/advanced_agents.md

@@ -0,0 +1,33 @@
+# KB: Advanced Agent Prototypes (Phase 2)
+
+This module documents the second wave of advanced agents implemented for the EbookBuilder ecosystem.
+
+## 1. Global Localization Agent
+- **Function**: `localize_content`
+- **Role**: High-fidelity translation and cultural adaptation.
+- **Use Case**: Expanding book distribution to non-English speaking markets.
+
+## 2. Legal & Copyright Guard
+- **Function**: `legal_copyright_scan`
+- **Role**: Intellectual property protection and plagiarism detection.
+- **Use Case**: Pre-publishing compliance check and licensing generation.
+
+## 3. Interactive Companion Agent
+- **Function**: `create_character_companion`
+- **Role**: Deploys interactive character chatbots to Hugging Face Spaces.
+- **Use Case**: Marketing and community engagement via interactive lore.
+
+## 4. Sentiment & Beta-Reader Analyst
+- **Function**: `analyze_reader_sentiment`
+- **Role**: Data-driven analysis of emotional impact and narrative pacing.
+- **Use Case**: Iterative editing based on reader feedback.
+
+## 5. Accessibility & Universal Design
+- **Function**: `optimize_accessibility`
+- **Role**: Ensures WCAG compliance and dyslexia-friendly formatting.
+- **Use Case**: Preparing ebooks for institutional and library distribution.
+
+## 6. Plot Continuity & Sequel Architect
+- **Function**: `build_continuity_graph`
+- **Role**: Narrative mapping and conflict detection across series.
+- **Use Case**: Maintaining a "Series Bible" for complex, multi-volume works.

knowledge/agent_prototypes.md

@@ -0,0 +1,33 @@
+# KB: Agent Prototypes & Multi-Agent Workflows
+
+This module documents the prototype agents implemented in the EbookBuilder MCP server.
+
+## 1. Research & Fact-Checker
+- **Function**: `fact_check_text`
+- **Role**: Validates claims and provides citations.
+- **Usage**: Call this after generating a non-fiction chapter or a historically accurate scene.
+
+## 2. Multi-Modal Illustrator
+- **Function**: `generate_illustration_prompt`
+- **Role**: Translates narrative descriptions into visual prompts for image generation.
+- **Usage**: Automates the creation of internal book art and covers.
+
+## 3. Audiobook (TTS) Synthesis
+- **Function**: `synthesize_audiobook_chapter`
+- **Role**: Queues text for conversion to speech using Parler-TTS or ElevenLabs.
+- **Usage**: Used to create multi-format releases (Ebook + Audiobook).
+
+## 4. Marketing & Metadata
+- **Function**: `generate_marketing_package`
+- **Role**: Creates sales blurbs, social media campaigns, and SEO tags.
+- **Usage**: Call during the final "Publishing" phase.
+
+## 5. Token & Cost Auditor
+- **Function**: `audit_project_costs`
+- **Role**: Monitors infrastructure spend and token consumption.
+- **Usage**: Run at the end of each work session to track project budget.
+
+## 6. Human-in-the-Loop Review
+- **Function**: `request_human_review`
+- **Role**: Creates a checkpoint that requires manual approval before proceeding.
+- **Usage**: Critical for maintaining authorial quality control.

knowledge/agents.md

@@ -0,0 +1,16 @@
+# KB: Agent Orchestration & Autonomy
+
+In the EbookBuilder ecosystem, "Agents" are autonomous units of logic that collaborate to solve complex problems.
+
+## Types of Agents
+1. **Manager Agent**: Coordinates the high-level plan (The "Director").
+2. **Worker Agents**: Specialize in narrow tasks like "Cover Design" or "Markdown Linting".
+3. **Validation Agents**: Verify the output of worker agents against a set of rubrics.
+
+## Orchestration Patterns
+- **Sequential**: Agent A finishes, then Agent B starts (e.g., Draft -> Edit).
+- **Parallel**: Multiple agents work on different chapters simultaneously.
+- **Hierarchical**: A manager agent delegates sub-tasks to subordinate agents and aggregates the results.
+
+## MCP Integration
+Agents communicate via the **Model Context Protocol**, allowing them to share tools and resources (like the Hugging Face Hub) seamlessly.

knowledge/api_wizard.md

@@ -0,0 +1,15 @@
+# KB: API Wizard MCP Server
+
+The **API Wizard** is a specialized agent role designed to automate the lifecycle of API integration within an MCP (Model Context Protocol) environment.
+
+## Capabilities
+- **Schema Analysis**: Automatically parses OpenAPI/Swagger specifications.
+- **Tool Generation**: Dynamically creates MCP tool definitions from endpoint descriptions.
+- **Authentication Handling**: Manages headers, tokens, and OAuth2 flows securely.
+- **Error Mapping**: Translates complex API error codes into human-readable debugging hints for the LLM.
+
+## Workflow
+1. **Discovery**: Point the Wizard at a URL or JSON schema.
+2. **Drafting**: The Wizard proposes a set of tool definitions (name, description, input schema).
+3. **Validation**: Testing the generated tools against a sandbox environment.
+4. **Deployment**: Exporting the configuration to the `mcpServers` section of the agent config.

knowledge/book_writer.md

@@ -0,0 +1,13 @@
+# KB: Book Writer Agent
+
+The **Book Writer Agent** is the core creative engine. It transforms outlines into prose while adhering to specific stylistic guidelines.
+
+## Responsibilities
+- **Drafting**: Writing long-form content based on chapter briefs.
+- **Tone Consistency**: Ensuring the voice remains stable across 50,000+ words.
+- **Character Tracking**: Maintaining a "World Bible" dataset to avoid continuity errors (e.g., eye color changes or teleporting characters).
+
+## Tools Used
+- **Knowledge Base Query**: Accessing research modules to ensure factual accuracy in non-fiction or internal consistency in fiction.
+- **Memory Buffer**: A rolling window of previous chapter summaries.
+- **Critique Loop**: A secondary "Editor" pass to identify and fix repetitive phrasing or pacing issues.

knowledge/domain_router.md

@@ -0,0 +1,12 @@
+# KB: Domain Router
+
+The **Domain Router** is the traffic controller of the EbookBuilder ecosystem, responsible for directing requests to the correct agent or service based on the context of the task.
+
+## Functions
+- **Contextual Routing**: Analyzes incoming user prompts to determine if they need a "Creative Writer", an "API Wizard", or a "Technical Editor".
+- **Multi-Tenant Support**: Maps custom subdomains (e.g., `user-1.ebookbuilder.com`) to specific Hugging Face Space instances.
+- **Load Balancing**: Distributes heavy generation tasks across multiple backend model endpoints to maintain responsiveness.
+
+## Architecture
+- **Layer 7 Routing**: Operates at the application level to inspect headers and path parameters.
+- **Failover Logic**: If a specific model provider is down, the router automatically switches to a fallback (e.g., switching from Vertex AI to Hugging Face Inference Endpoints).

knowledge/formatting.md

@@ -0,0 +1,15 @@
+# EbookBuilder: Formatting & Conversion
+
+Once content is generated, it must be transformed into a reader-ready format.
+
+## Standard Structure
+- `metadata.yaml`: Contains title, author, and CSS paths.
+- `chapters/`: Individual markdown files.
+- `assets/`: Images and fonts.
+
+## Conversion Tools
+- **Pandoc**: The "Swiss army knife" of document conversion. Use it to go from Markdown to EPUB or PDF.
+- **KindleGen**: For final MOBI/AZW3 optimization.
+
+## Visuals
+- Use **FLUX.1** or **Stable Diffusion XL** for cover art and internal illustrations.

knowledge/generation.md

@@ -0,0 +1,12 @@
+# EbookBuilder: Content Generation
+
+The generation module focuses on producing coherent and engaging text.
+
+## Strategies
+1. **Recursive Outlining**: Generate a high-level outline, then expand each point into sub-points before drafting.
+2. **Context Window Management**: Pass previous chapter summaries to the model to ensure narrative consistency.
+3. **Style Injection**: Use system instructions to enforce specific literary styles or technical tones.
+
+## Recommended Models
+- **General Purpose**: Llama-3-70B, Qwen-2.5.
+- **Creative Writing**: Claude-3.5-Sonnet (via API) or specialized fine-tuned models on HF.

knowledge/hostinger_hosting.md

@@ -0,0 +1,18 @@
+# KB: Hostinger Hosting & Deployment
+
+The **Hostinger Agent** handles the final mile of the ebook project: securing a domain and hosting the sales pages and companion apps.
+
+## Core Capabilities
+- **Account Usage**: Monitoring hosting resources via `hostinger_get_account_info`.
+- **Domain Management**: Listing and verifying owned domains with `hostinger_list_domains`.
+- **DNS Configuration**: Using `hostinger_add_dns_record` to point domains to sales pages (e.g., A records) or verify ownership for external services (e.g., TXT records for Stripe/Google).
+- **Automated Deployment**: Using `hostinger_deploy_static_site` to push the sales page copy generated by the Sales Page Agent directly to the web.
+
+## Workflow Integration
+1. **Purchase**: The user buys a domain on Hostinger.
+2. **Setup**: The Hostinger Agent adds necessary DNS records for SSL and CDN.
+3. **Draft**: The Sales Page Agent creates the high-converting copy.
+4. **Publish**: The Hostinger Agent deploys the copy to the domain's `public_html` directory.
+
+## Connection
+The agent uses the `HOSTINGER_API_KEY` for secure, authenticated REST API requests to the Hostinger backend.

knowledge/intro.md

@@ -0,0 +1,8 @@
+# EbookBuilder: Introduction
+
+EbookBuilder is an automated system for creating high-quality ebooks using Artificial Intelligence. By leveraging the Hugging Face ecosystem, it streamlines the process from initial outline to final publication.
+
+## Core Philosophy
+- **Automation with Oversight**: AI handles the bulk of content creation, while the author provides direction and refinement.
+- **Portability**: Content is maintained in Markdown for maximum compatibility.
+- **Scalability**: High-performance models on Hugging Face ensure that even complex, multi-volume projects are handled efficiently.

knowledge/market_research.md

@@ -0,0 +1,17 @@
+# KB: Market Research Agent
+
+The **Market Research Agent** is designed to provide authors and publishers with data-driven insights into specific book niches and market trends.
+
+## Core Capabilities
+- **Trend Identification**: Analyzes current high-performing topics and sub-genres.
+- **Competitive Intelligence**: Evaluates successful titles in the same niche (pricing, covers, blurbs).
+- **Audience Profiling**: Defines the ideal reader, their demographics, and their motivations.
+- **Keyword Optimization**: Suggests high-traffic keywords for Amazon (KDP) and Google Search.
+
+## Workflow Integration
+The Market Research Agent should be called at the very beginning of a project (The "Discovery Phase") and periodically during the writing process to ensure the book remains commercially viable.
+
+## Tool Function
+- **Function**: `perform_market_research(niche: str)`
+- **Output**: A comprehensive report covering trends, competitors, audience, and keywords.
+- **AI Engine**: Powered by Llama-3-8B-Instruct for high-fidelity market analysis.

knowledge/meta_agent.md

@@ -0,0 +1,22 @@
+# KB: Meta Orchestrator & System Upgrades
+
+This module documents the upgrade of the EbookBuilder agents from static prototypes to dynamic, Inference-powered tools, and the introduction of the **Meta Orchestrator**.
+
+## 1. The Meta Orchestrator (Meta Agent)
+- **Function**: `meta_orchestrator`
+- **Role**: The "Brain" of the system. It takes high-level user goals and decomposes them into specific tool calls.
+- **Workflow**:
+    1. Analyze user intent.
+    2. Map intent to the 12+ specialized tools.
+    3. Suggest a sequence of execution.
+
+## 2. Upgraded AI Capabilities
+All specialized agents now use the **Hugging Face Inference API** (via `InferenceClient`) for real-time processing:
+- **Llama-3 Integration**: Powers the Meta Agent, Fact-Checker, Illustrator, and Legal Guard for complex reasoning.
+- **DistilBERT Integration**: Powers the Sentiment Analyst for high-speed text classification.
+- **Style-Preserving Translation**: Uses state-of-the-art models for the Localization Agent.
+
+## 3. Operational Benefits
+- **Real-Time Results**: No longer returns "mock" data; tools now provide actual AI-generated insights.
+- **Scalability**: Tasks are offloaded to Hugging Face's global inference infrastructure.
+- **Intelligence**: The Meta Agent ensures that complex requests (e.g., "Translate my book and generate a marketing plan for it") are handled with logical consistency.

knowledge/openai_integration.md

@@ -0,0 +1,22 @@
+# KB: OpenAI Integration & Hybrid AI
+
+The EbookBuilder system now supports a hybrid AI architecture, combining the open-source power of Hugging Face with the advanced reasoning and generative capabilities of OpenAI.
+
+## 1. GPT-4o Integration
+- **Function**: `generate_content_openai`
+- **Role**: High-fidelity drafting, complex character development, and intricate plot planning.
+- **Why**: Use GPT-4o for tasks that require the highest level of linguistic nuance or multi-step logic.
+
+## 2. DALL-E 3 Integration
+- **Function**: `generate_image_dalle`
+- **Role**: Premium cover design and photorealistic internal illustrations.
+- **Why**: DALL-E 3 excels at following complex visual instructions and embedding text into images.
+
+## 3. Hybrid Orchestration
+The **Meta Orchestrator** has been upgraded to route tasks dynamically between HF and OpenAI based on the requirements:
+- **Research/Fact-Checking**: Handled by Llama-3 (HF).
+- **Prose/Creativity**: Handled by GPT-4o (OpenAI).
+- **Marketing/Commerce**: Handled by Llama-3 (HF).
+
+## Setup
+To use these features, ensure the `OPENAI_API_KEY` environment variable is set in your session.

knowledge/publishing.md

@@ -0,0 +1,12 @@
+# EbookBuilder: Publishing & Distribution
+
+Getting your book into the hands of readers.
+
+## Platforms
+1. **Amazon KDP**: The primary marketplace for self-published authors.
+2. **Leanpub**: Excellent for technical books and "work-in-progress" publishing.
+3. **Gumroad/Koji**: For direct-to-reader sales.
+
+## Hugging Face Integration
+- **Spaces**: Create a demo or a "reader" app for your book.
+- **Datasets**: Host the raw text and training data if the book is an open-source project.

knowledge/sales_marketing.md

@@ -0,0 +1,24 @@
+# KB: Sales, Marketing & Payments
+
+This module documents the agents responsible for the commercial success of your ebook, focusing on traffic generation, conversion, and monetization.
+
+## 1. The Blogger Agent
+- **Function**: `generate_blog_post`
+- **Role**: Content marketer and SEO specialist.
+- **Workflow**: Creates long-form educational or entertaining content that provides value to the reader while positioning your ebook as the logical "next step."
+
+## 2. The Sales Page Agent
+- **Function**: `create_sales_page`
+- **Role**: Conversion rate optimization (CRO) specialist.
+- **Workflow**: Uses psychological triggers (scarcity, social proof, benefit-driven headlines) to draft landing page copy that turns visitors into buyers.
+
+## 3. The Stripe Integration Agent
+- **Function**: `setup_stripe_payment`
+- **Role**: Financial architect.
+- **Workflow**: Generates the exact technical configuration required to securely accept payments via Stripe Checkout, including product metadata and price IDs.
+
+## Integrated Commercial Workflow
+1. **Research**: Use the Market Research agent to find a profitable niche.
+2. **Attract**: Use the Blogger agent to create articles that rank on search engines.
+3. **Convert**: Use the Sales Page agent to draft the landing page.
+4. **Monetize**: Use the Stripe agent to handle the transaction.

knowledge/supabase_integration.md

@@ -0,0 +1,21 @@
+# KB: Supabase Database Integration
+
+The **Supabase Agent** provides the persistence layer for the EbookBuilder ecosystem, managing ebook metadata, sales records, and transaction logs.
+
+## Core Capabilities
+- **Metadata Management**: Uses `db_upsert_ebook` to keep track of book titles, authors, status (draft/published), and GCS/HF paths.
+- **Sales Intelligence**: Uses `db_get_sales_report` to provide the author with real-time insights into book performance.
+- **Audit Logging**: Uses `db_log_transaction` to maintain a secure and immutable record of every payment and generation event.
+
+## Database Schema (Recommended)
+1. **ebooks**: `id`, `title`, `author`, `status`, `content_url`, `created_at`
+2. **sales**: `id`, `ebook_id`, `amount`, `currency`, `customer_email`, `created_at`
+3. **transactions**: `id`, `event_type`, `payload`, `status`, `created_at`
+
+## Workflow Integration
+- **Post-Generation**: Automatically upsert ebook metadata after a successful manuscript completion.
+- **Post-Sale**: Log the transaction details immediately after a successful Stripe Checkout callback.
+- **Reporting**: Query the sales table to generate monthly performance reviews via the Meta Orchestrator.
+
+## Connection
+The agent uses the Service Key for administrative access, ensuring it can manage all tables within the `vrspcqzajxupormgqhpe` project.

knowledge/webhooks.md

@@ -0,0 +1,13 @@
+# KB: Webhooks & Event-Driven Architecture
+
+Webhooks enable the EbookBuilder and API Wizard to respond to real-time events from external services (e.g., GitHub, Stripe, Hugging Face).
+
+## Implementation
+- **Endpoints**: Secure HTTPS endpoints that listen for `POST` requests.
+- **Payload Verification**: Using HMAC signatures (e.g., `X-Hub-Signature`) to ensure requests originate from a trusted source.
+- **Asynchronous Processing**: Webhooks should immediately return a `202 Accepted` and queue the task for an agent to handle.
+
+## Common Events
+- `repo_update`: Triggers a re-download of a knowledge base module.
+- `generation_complete`: Notifies the user when an LLM chapter draft is ready.
+- `subscription_change`: Manages access tiers for the EbookBuilder interface.