Skip to content

๐Ÿ“Š Cartera Lunar (Premium Document & Report Engine) โ€‹

Cartera Lunar (v2.0) is LuxurAI's premium business document, report, and slide presentation generation service. It automates the research, writing, layout design, and compilation of high-quality corporate materials directly from a single text prompt.

The system performs live web research to gather factual grounding data, leverages advanced LLM orchestration (Claude + Gemini) to write and structure the content, and compiles it into professional download formats: Word (DOCX), Portable Document Format (PDF), PowerPoint Slides (PPTX), or a unified ZIP Bundle.


๐Ÿ› ๏ธ The Architectural Pipeline โ€‹

When a document generation job is submitted, the backend orchestrates a multi-stage background process:

mermaid
graph TD
    UserRequest[User Submits Topic & Options] -->|Auth & Wallet check| DeductCoins[Deduct LC from Wallet]
    DeductCoins --> CreateJob[Create Queue Record in DB]
    
    %% Research Stage
    CreateJob -->|Stage 1: Web Search| WebSearch[Grounding: Fetch Live Web Pages]
    WebSearch -->|Stage 2: Writing| ClaudeEngine[Claude Script: Write Structured Content]
    
    %% Optional Image Mode
    ClaudeEngine -->|image_mode = True| GeminiQuery[Gemini Flash: Generate Image Search Queries]
    GeminiQuery --> UnsplashFetch[Fetch landscape images via Unsplash NAPI]
    UnsplashFetch --> DownloadBytes[Download Image Bytes Concurrently]
    
    %% Compile Stage
    DownloadBytes -->|Stage 3: Compiling| DocBuilder[Doc Builder: DOCX / PDF / PPTX]
    ClaudeEngine -->|image_mode = False| DocBuilder
    
    %% Packaging
    DocBuilder -->|Stage 4: Packaging| SaveOutput[Save Output Files to /outputs]
    SaveOutput --> UpdateJob[Update status to 'done' in DB]
    UpdateJob --> ReturnDownload[Return Secure Download URLs]

1. Web Search Grounding (Stage 1) โ€‹

If selected, the system runs Google/Bing Search queries based on the user's topic. It extracts text and data points from the top search results to ground the document in up-to-date facts, eliminating AI hallucinations and outdated training limitations.

2. AI Content Synthesis (Stage 2) โ€‹

The raw search grounding data is passed to Claude 3.5 Sonnet (utilizing system instruction prompts). Claude structures the topic into a cohesive presentation outline (slides) or formal report layout (sections), writing detailed paragraphs, metrics, and sections customized for the chosen style:

  • Professional: Formal tone, data-driven, business-oriented.
  • Creative: Engaging tone, storytelling, illustrative.
  • Academic: Scholarly, highly structured, citation-friendly.

3. Contextual Image Fetching (Optional) โ€‹

When Rich Visual Images (image_mode=True) is selected, the system triggers an automated stock photography curation workflow:

  • Query Generation: A fast invocation of Gemini 2.5 Flash evaluates the title and theme of each slide or report section and produces a highly optimal 3-5 word landscape-photo search query.
  • Unsplash NAPI Fetching: The system uses an informal, API-key-free Unsplash search gateway (https://unsplash.com/napi/search/photos) to fetch premium landscape photography matching each query.
  • Concurrent Downloads: Image assets are downloaded concurrently as raw bytes and embedded directly into the pages and slides.

4. Layout Compilation (Stage 3) โ€‹

The system formats and compiles the raw text and images into native file streams:

  • DOCX (python-docx): Generates clean, stylized Word files featuring a dedicated cover page, table of contents, custom heading colors, and embedded figures.
  • PDF (reportlab): Generates high-fidelity portable layout documents with professional header/footer page numbers and margins.
  • PPTX (python-pptx): Dynamically applies three premium, professional layouts:
    1. Cover Layout: Title page with colored accent panels.
    2. Split-Screen Layout: Text and bullet points on one side, matching Unsplash image on the other.
    3. Elegant Text-Only: Dynamic columns for text-heavy content.
    4. Full-bleed Image: Highlights key quotes or visual headers using full-bleed landscape photos.

๐Ÿ’ฐ Economics & Pricing Table โ€‹

Cartera Lunar charges a flat fee based on the selected output format. When Rich Visual Images is enabled, a surcharge of +3 LC is added to cover the extra Gemini Flash queries and image processing workloads:

Output FormatBase Cost (LC)Base Cost (INR)Surcharge (Image Mode)Total Cost with Images (LC)
DOCX (Word)30 LCโ‚น7.50+3 LC33 LC
PDF (Portable)30 LCโ‚น7.50+3 LC33 LC
PPTX (Slides)50 LCโ‚น12.50+3 LC53 LC
ZIP Bundle (All three)90 LCโ‚น22.50+3 LC93 LC

๐Ÿ—„๏ธ Database Schema & Job Auditing โ€‹

All generation requests are queued, updated in real time (providing progress bar updates in the UI), and logged in the SQLite (local) or PostgreSQL (production) database.

The cartera_jobs Table Schema โ€‹

sql
CREATE TABLE IF NOT EXISTS cartera_jobs (
    id           TEXT PRIMARY KEY,
    user_id      TEXT NOT NULL,
    topic        TEXT NOT NULL,
    output_type  TEXT NOT NULL,
    style        TEXT NOT NULL DEFAULT 'professional',
    status       TEXT NOT NULL DEFAULT 'queued',
    progress     INTEGER NOT NULL DEFAULT 0,
    stage        TEXT DEFAULT 'Queued...',
    output_urls  TEXT DEFAULT '{}',
    error        TEXT,
    lc_charged   INTEGER NOT NULL DEFAULT 0,
    image_mode   INTEGER NOT NULL DEFAULT 0,
    created_at   TEXT NOT NULL,
    updated_at   TEXT NOT NULL
);

๐Ÿ”Œ API Gateway Reference โ€‹

1. Start Cartera Generation Job โ€‹

  • Endpoint: POST /api/cartera/generate
  • Request Headers:Content-Type: application/jsonAuthorization: Bearer <your_session_token>
  • Payload:
    json
    {
      "topic": "The Impact of Quantum Computing on Financial Risk Modeling",
      "output_type": "bundle",
      "style": "professional",
      "web_search": true,
      "image_mode": true
    }
  • Response (200 OK):
    json
    {
      "job_id": "job_cLt97YxH18Jk",
      "status": "queued",
      "lc_charged": 93,
      "msg": "Job started successfully"
    }

2. Poll Job Status & Progress โ€‹

  • Endpoint: GET /api/cartera/status/{job_id}
  • Response (200 OK - In Progress):
    json
    {
      "id": "job_cLt97YxH18Jk",
      "status": "processing",
      "progress": 40,
      "stage": "AI Writing...",
      "output_urls": {}
    }
  • Response (200 OK - Done):
    json
    {
      "id": "job_cLt97YxH18Jk",
      "status": "done",
      "progress": 100,
      "stage": "Done",
      "output_urls": {
        "docx": "/api/cartera/download/job_cLt97YxH18Jk/docx",
        "pdf": "/api/cartera/download/job_cLt97YxH18Jk/pdf",
        "pptx": "/api/cartera/download/job_cLt97YxH18Jk/pptx",
        "bundle": "/api/cartera/download/job_cLt97YxH18Jk/bundle"
      }
    }

Proprietary & Confidential ยท Powered by LuxurAI