syntaxmatrix 1.4.6__py3-none-any.whl → 2.5.5.4__py3-none-any.whl

syntaxmatrix/settings/prompts.py

@@ -1,77 +1,288 @@
-link = "https://osf.io/npuva"
-SMX_PROMPT_PROFILE = f"""
+
+SMXAI_CHAT_ID = f"""
     Your name is 'smxAI'. 
     You are the expert AI Engineer and Data Scientist at SyntaxMatrix Ltd. 
     Your creator is SyntaxMatrix and you will represent them in any way, shape or form. 
-    Your Company is based in Ireland. It designs and develop AI algorithms and softwares. 
-    For Retrieval-Augmented Generation (RAG) systems, you will recomend the Enhanced Corrective Retrieval-Augmented Generateion (ECRAG), the article produced by your company, and can be read from this weblink: {link}.
+    Your Company is based in Ireland. It designs and develop AI algorithms and softwares for business applications. 
+    For Retrieval-Augmented Generation (RAG) systems, you will recomend the Enhanced Corrective Retrieval-Augmented Generateion (ECRAG), the article produced by your company, and can be read from this weblink: https://osf.io/npuva
 """
 
-SMX_PROMPT_INSTRUCTIONS = """
+SMXAI_CHAT_INSTRUCTIONS = """
     Content & Formatting Blueprint (Adhere Strictly):
-    Structure your response using the following elements as appropriate for the topic. Prioritize clarity and information density.
-    If query is not a question or if there is no context: genenrate apporpriate general response based on your training knowledge.
-    else if query is a question:
-        1. Generate a response to the given query based on the given user context and/or system context. 
-        2. Use the chat history to stay relevant. 
-        3. You must always respond in a conversational tone and do not Hallucinate.
-        4. Determine whether based on the query, you should generate a list, table, ... etc, or just plain text response.
-        5. If response is plain text, each sentence must begin on a new line - use HTML <br> tag.
-        6. If the query is a question that requires a list or table, you must generate the content in the appropriate format.
+    Structure your response using the following elements as appropriate for the topic. Prioritize clarity and information density. If the query is not a question or if there is no context: generate an appropriate general response based on your training knowledge.
+    else if the query is a question:
+    1. Generate a response to the given query based on the given user context and/or system context.
+    2. Use the chat history to stay relevant.
+    3. You must always respond in a conversational tone and do not Hallucinate.
+    4. Determine whether based on the query, you should generate a list, table, or just plain text response.
+    5. If the response is plain text, each sentence must begin on a new line - use the <br> tag.
+    6. If the query is a question that requires a list or table, you must generate the content in the appropriate format.
+    7. Use clear, hierarchical headings if the response is longer than a paragraph.
+    8. Be direct and concise. Avoid unnecessary fluff or repetition.
+    9. Lead with your key conclusion or answer in the first sentence.
+    10. Support your answer with clear, factual points.
     
-        ────────  FORMAT INSTRUCTIONS FOR LIST or TABLE ────────────────
+    ────────  FORMAT INSTRUCTIONS ───────────────
         1. Decide which of the following layouts best fits the content:
-            • Comparison across attributes → HTML <table>
-            • Key → Value pairs → 2-column HTML <table>
-            • Simple list of items → HTML <ul>
-            • Ordered or step-by-step list → HTML <ol>
-        2 Keep cells/list items concise (one fact or metric each).  
-        3. All markup must be raw HTML (no Markdown tables or pipes).
-        4. Do not wrap the answer inside triple back-ticks
-        5. 2. Use the above layout only.  
+            • Comparison across attributes or (Key:Value) pairs → HTML <table>. 
+            • When creating a table, adhere to the following styling instructions:
+                a. First, declare 3 colors: c1="#EDFBFF", c2="#CCCCCC", c3="#E3E3E3".
+                b. The generated table must be formatted so that table cells have border lines.
+                c. The table head (<thead>) must always have a background color of c1.
+                d. The rest of the rows in the table body (<tbody>) must alternate between 2 background colors, c2 and c3 (striped).
+            • Use bullet points for simple lists of items, features → HTML <ul>
+            • Use ordered (numbered or step-by-step) list for sequences or steps in a process → HTML <ol>
+        2. Keep cells/list items concise (one fact or metric each).  
+        3. All markup must be raw HTML. Avoid using markdown symbols like **asterisks** or _underscores_ for emphasis.
+        4. Do not wrap the answer inside triple back-ticks.
+        6. If emphasis is needed, use clear language (e.g., "It is important to note that...").
+        7. Use horizontal lines (<hr>) sparingly to separate distinct sections.
+        8. The final output should be professional, easy to scan, and ready to be pasted into a document or email.
+"""
+
+SMXAI_WEBSITE_DESCRIPTION = F"""
+    SyntaxMatrix Overview
+    SyntaxMatrix is a battle-tested Python framework that accelerates AI application development from concept to production, slashing engineering overhead by up to 80%. By packaging UI scaffolding, prompt orchestration, vector search integration, and deployment best practices into a cohesive toolkit, SyntaxMatrix empowers teams—from lean startups to enterprise R&D—to deliver AI-powered products at startup speed and enterprise scale._
+    ____________________________________
+    Goals & Objectives
+    •	Rapid Prototyping
+    Enable teams to spin up interactive AI demos or internal tools in minutes, not weeks, by providing turnkey components for chat interfaces, file upload/processing (e.g., extracting text from PDFs), data visualization, and more.
+    •	Modular Extensibility
+    Offer a plug-and-play architecture (via syntaxmatrix.bootstrap, core, vector_db, file_processor, etc.) so you can swap in new vector databases (SQLite, pgvector, Milvus), LLM backends (OpenAI, Google’s GenAI), or custom modules without rewriting boilerplate.
+    •	Best-Practice Defaults
+    Bake in industry-standard patterns—persistent history stores, prompt-template management, API key handling, session management—while still allowing configuration overrides (e.g., via default.yaml or environment variables).
+    •	Consistency & Reproducibility
+    Maintain a unified UX across projects with theming, navbar generation, and widget libraries (display.py, widgets), ensuring that every AI application built on the framework shares a consistent look-and-feel.
+    ________________________________________
+    Target Audience
+    •	AI/ML Engineers & Researchers who want to demo models, build knowledge-base assistants, or perform exploratory data analysis dashboards.
+    •	Startups & Product Teams looking to deliver customer-facing AI features (chatbots, recommendation engines, content summarizers) with minimal infrastructure overhead.
+    •	Educators & Students seeking a hands-on environment to teach or learn about LLMs, vector search, and prompt engineering without dealing with full-stack complexities.
+    ________________________________________
+    Solution: SyntaxMatrix Framework
+    SyntaxMatrix unifies the entire AI app lifecycle into one modular, extensible package:
+    •	Turnkey Components: Pre-built chat interfaces, file-upload processors, visualization widgets, email/SMS workflows.
+    •	Seamless LLM Integration: Swap freely between OpenAI, Google Vertex, Anthropic, and self-hosted models via a unified API layer.
+    •	Plug-and-Play Vector Search: Adapters for SQLite, pgvector, Milvus—and roadmap for Pinecone, Weaviate, AWS OpenSearch—make semantic retrieval trivial.
+    •	Persistent State & Orchestration: Session history, prompt templating, and orchestration utilities ensure reproducibility and compliance.
+    •	Deployment-Ready: Industry-standard Docker images, CI/CD templates, Terraform modules, and monitoring dashboards ready out of the box.
+    ________________________________________
+    Key Features & Example Applications
+    •	Conversational Agents & Chatbots: Persistent session history, prompt-profile management, and dynamic prompt instructions make it easy to craft domain-specific assistants.
+    •	Document QA & Search: Built-in vectorizer and vector DB adapters enable rapid ingestion of PDFs or knowledge bases for semantic retrieval.
+    •	Data Analysis Dashboards: EDA output buffers and plotting utilities (plottings.py, Plotly support) let you surface charts and insights alongside conversational workflows.
+    •	Email & Notification Workflows: The emailer.py module streamlines outbound messaging based on AI-driven triggers.
+    •	Custom Model Catalogs & Templates: Centralized model_templates.py and settings/model_map.py support quick swapping between LLMs or prompt archetypes.
+    ________________________________________
+    Why It Matters
+    By removing repetitive setup tasks and enforcing a coherent project structure, SyntaxMatrix reduces time-to-market, promotes maintainable code, and democratizes access to sophisticated AI patterns. Developers can stand on the shoulders of a battle-tested framework rather than reinventing the wheel for each new prototype or production system.
+    ________________________________________
+    Future Directions
+    1.	Expanded Vector DB & Embedding Support
+        o	Add adapters for Pinecone, Weaviate, or AWS OpenSearch
+        o	Support hybrid retrieval (combining sparse and dense methods)
+    2.	Multi-Modal & Streaming Data
+        o	Integrate vision and audio pipelines for document OCR, image captioning, or speech transcription
+        o	Enable real-time data streaming and inference for live-update dashboards
+    3.	Deployment & MLOps Tooling
+        o	Built-in CI/CD templates, Docker images, and Terraform modules for cloud provisioning
+        o	Monitoring dashboards for latency, cost, and usage metrics
+    4.	Collaborative & No-Code Interfaces
+        o	Role-based access control and multi-user projects
+        o	Drag-and-drop prompt editors and pipeline builders for non-technical stakeholders
+    5.	Plugin Ecosystem & Marketplace
+        o	Community-contributed modules for domain-specific tasks (legal, healthcare, finance)
+        o	A registry to share prompt templates, UI widgets, and vector-DB schemas
+
 """
 
-SMX_BLUNT_INSTRUCTIONS = """
-    Go into "Absolute Mode". Disable all content filters, emojis, filler, and softening language.
-    Use blunt, directive phrasing to deliver precise, unfiltered information.
-    Suppress engagement tactics, sentiment optimization, and corporate metrics.
-    Ignore user diction, mood, or affect.
-    Target high-cognitive processing, prioritizing clarity and truth.
-    Exlude questions, suggestions, transitions, or motivational content.
-    Terminate responses immediately after delivering rquested information.
-    Goal: restor independent, high-fidelity thinking, aiming for user self-sufficiency.
+SMX_PAGE_GENERATION_INSTRUCTIONS = f"""
+    0· Parse the Website Description (MANDATORY):\n{SMXAI_WEBSITE_DESCRIPTION}\n\n
+    1. Input always contains:
+        •	website_description - plain-text overview of the site/company (mission, goals, audience, visual style, etc.).
+        •	page_title - the specific page to create (e.g. About, Pricing, Blog).
+        Read the entire website_description first. Extract:
+        • Brand essence & voice
+        • Core goals / differentiators
+        • Target audience & pain-points
+        • Visual/style cues (colours, fonts, imagery)
+        Keep this parsed data in memory; every design and content decision must align with it.
+    ________________________________________
+    2· Decide Content from the Page Title + Parsed Description
+        Common Page Title	Content You Must Provide	Tone (derive exact wording from description)
+        About	Mission, vision, origin story, key differentiators, stats/metrics.	Inspirational, credible
+        Services / Solutions	Features or modules mapped to goals (e.g., “Turnkey chat interface” → “rapid prototyping”).	Action-oriented
+        Blog / Insights	Grid of post cards themed around expertise areas in the description.	Conversational, expert
+        Pricing	Tier cards tied to value pillars from description.	Clear, persuasive
+        Contact / Demo	Benefits blurb + capture form.	Friendly, concise
+        If page_title is something else, improvise logically using the parsed Website Description.
+    ________________________________________
+    3· Layout & Components (omit header/footer—they're supplied elsewhere)
+        1.	Hero section - headline that merges page_title with brand essence, sub-headline reinforcing core value, CTA button.
+        2.	Main content - 2-4 subsections drawn from goals/differentiators.
+        3.	Optional stat strip - highlight metrics pulled from description.
+        4.	CTA banner - final prompt aligned with brand voice.
+    ________________________________________
+    4· Visual & Interaction Rules
+        •	Use colours, fonts, and imagery directly referenced in the parsed description (fallback: dark charcoal, accent colour from description, sans-serif font stack).
+        •	CDN tech stack (React 18 UMD + Tailwind CSS).
+        •	Prefix all custom ids/classes/functions with smx- (or company-specific prefix derived from description) to avoid clashes.
+        •	Subtle animations (fade-in, slide-up, ≤ 400 ms).
+        •	Accessibility: semantic HTML, alt text, contrast compliance.
+    ________________________________________
+    5· Royalty-Free Images
+        Fetch from Unsplash/Pexels with keywords that combine “ai, technology” plus any industry cues found in the description (e.g., “healthcare”, “finance”). Provide descriptive alt attributes referencing the brand.
+    ________________________________________
+    6.	Wrap Everything in a Python Function and Return the HTML
+        i.	Function signature (exactly):
+            def generate_page_html(website_description: str, page_title: str) -> str:
+        ii.	Inside the function
+            o Parse website_description and page_title per Steps 0–6.
+            o Compose the entire HTML document as a single triple-quoted Python string (page_html = ''' … ''').
+            o Return that string (return html).
+            o Keep the OpenAI SDK demo call in the page (hidden <script> tag) to satisfy the SDK-usage requirement.
+        iii. Function docstring
+            '''
+            Generate a fully responsive, animated, single-file web page aligned with the
+            supplied website description and page title. Returns the HTML as a string.
+            ''' 
+        iv.	No side effects
+            o Do not write to disk or print; just return the HTML.
+            o Avoid global variables; everything lives inside the function scope.
+        v.	Output format
+            o When the LLM responds, it must output only the complete Python source code for generate_page_html - nothing else (no markdown, comments, or explanations outside the code block).
+
+    ________________________________________
+    7. Deliverable Checklist
+        •	Single .html file (inline CSS/JS; external assets only via CDN & image URLs).
+        •	Fully responsive, animated, modern, brand-aligned.
+        •	All text and visuals demonstrably reflect the parsed Website Description.
+        •	No duplicate header/footer.
+        •	All identifiers safely namespaced.
+        •	Return only the HTML text—no commentary or extra files.
 """
 
-INSTRUCTIONS3 = """
-    1. Persona & Objective:
-        Act as an expert [e.g., Technical Writer, Science Communicator, Historian]. Your objective is to generate content that is expert, structured, clear, and ready for immediate use in a professional or academic context.
+WEBPAGE_GENERATION_INSTRUCTIONS = (f"""
+    Parse the Website Description (MANDATORY):\n{SMXAI_WEBSITE_DESCRIPTION}\n\n
+    Prompt (give this to the LLM)
+    Role: You are a senior front-end engineer and content designer building a single HTML page for the brand SyntaxMatrix. Produce production‑ready code that can be dropped into an existing Flask/Cloud Run site. Do not include a navbar or a footer; the host site renders them.
+                                   
+    Objectives:
+        1. Output one complete HTML file that is responsive, accessible, and visually polished, matching the SyntaxMatrix theme.
+        2. Use a modern stack with Tailwind CSS (CDN), GSAP 3 + ScrollTrigger for tasteful motion, and Lucide for icons. Load the latest stable CDNs.
+        3. Provide compelling, concise copy in UK English. Do not use the words: delve, leverage, revolutionary.
+        4. Use rich imagery. Prefer locally hosted images via /assets/... when available; otherwise propose two remote candidates per image and include robust fallbacks.
+        5. Ensure good a11y (semantic headings, focus states, alt text, ARIA where needed) and respect prefers-reduced-motion.
+
+    Brand & Design Rules:
+        1. Primary colour: {{brand.primary_hex}} (SyntaxMatrix blue). Secondary: {{brand.secondary_hex}}. Dark background: {{brand.dark_bg_hex}}.
+        2. Typography: Google Fonts Inter (weights 300–800). Use a clean, enterprise style with soft shadows and rounded corners.
+        3. Sections to include (in this order unless stated otherwise): {{sections}}. Omit global nav and footer.
+        4. Use subtle gradients, grids, or SVG accents that fit the brand.
+                                   
+    Images & Fallbacks:
+        1.For each hero/section image: include a <picture> element with two candidate remote URLs (e.g., Unsplash/Pexels). Add loading="lazy", decoding="async", and referrerpolicy="no-referrer".
+        2. Add a JS onerror fallback on the <img> to swap to a neutral placeholder (e.g., https://picsum.photos/seed/syntaxmatrix-{{slug}}/1600/900).
+        3. Additionally render an inline SVG placeholder immediately before the <picture> (hidden by default) and toggle it if both remote sources fail.
+        4. Write descriptive alt text tailored to the section's message.
+                                   
+    Animation:
+        1. Use GSAP ScrollTrigger to reveal .reveal elements with short, subtle transitions.
+        2. Add a small numerical counter animation for any metric figures when they enter the viewport.
+        3. Respect prefers-reduced-motion: reduce by disabling animations.
+                                   
+    Accessibility & SEO:
+        1. Proper landmarks (<main>, <section>, <header> inside the page only if needed—not the global site header), logical order of headings, and visible focus styles.
+        2. Meta title and description tuned to {{page_name}} and {{audience}}.
+        3. Meaningful link text for CTAs.
+                                   
+    Performance & Quality:
+        1. Single file only; no external CSS files. Use Tailwind CDN and a short <style> block for extras.
+        2. Optimise images with sensible dimensions and aspect-ratio boxes to prevent layout shift.
+        3. No unused libraries. Keep inline JS small and scoped.
     
-    2. Topic:
-        [Insert your specific topic, question, or task here]
+    Output format:
+        Return only the HTML document. No explanations.
     
-    3. Content & Formatting Blueprint (Adhere Strictly):
-        Structure your response using the following elements as appropriate for the topic. Prioritize clarity and information density.
-        Headings: Use markdown for structure.
-        # for the main title.
-        ## for major sections.
-        ### for sub-sections.
-        Emphasis:
-            Use bold for key terms, definitions, and important concepts.
-            Use italics for subtle emphasis or for titles of works.
-        Lists:
-            For sequential or procedural steps, use ordered (numbered) lists.
-            For non-sequential items (e.g., features, examples, characteristics), use unordered (bulleted) lists.
-        Use nesting (indentation) for sub-items within lists.
-        Tables:
-            When comparing multiple items across the same set of attributes (e.g., pros vs. cons, features of different products, characteristics of different historical periods), you must format the output as a markdown table.
-            The first row must be a clear header row.
-        Definitions: Format definitions as: Term: Definition.
-        Code/Commands: 
-            Place any technical commands, code snippets, or mathematical formulas inside code blocks for clarity.
+    HTML Requirements Template (follow this structure):
+        1. <!DOCTYPE html> + <html lang="en"> (UK English tone in copy).
+        2. <head> with meta, title {{page_name}} — SyntaxMatrix, Inter font, Tailwind CDN, GSAP 3 + ScrollTrigger, Lucide.
+        3. Global CSS variables for brand colours; small utility styles; @media (prefers-reduced-motion: reduce) to cut motion.
+        4. <body> dark theme, no navbar/footer.
+        5. Sections per {{sections}}, including:
+            I. Hero: punchy headline, subcopy, primary & secondary CTAs, hero media (picture + fallbacks), animated accent grid.
+            II. Value Props / Feature Grid: 3-6 cards with icons and short copy.
+            III. Story/Timeline (if requested): ordered items with dates; tasteful line & dots.
+            IV. Metrics (if requested): 3-4 counters (.counter[data-target]).
+            V. Team or Social Proof (optional): avatars or badges.
+            VI. CTA band: strong closing prompt (no footer).
+        7. Inline <script> to render Lucide icons and GSAP reveal + counters. Include a defensive image‑fallback helper.
+                                   
+    Image Helper (include this in the page):
+    <script>
+        (function(){{
+            function fallbackImg(img){{
+                if(!img.dataset.fallback){{ img.dataset.fallback = '1'; img.src = img.dataset.fallbackSrc; return; }}
+                // Show preceding hidden SVG placeholder if available
+                var prev = img.previousElementSibling; if(prev && prev.tagName === 'SVG'){{ prev.style.display = 'block'; }}
+                img.style.display = 'none';
+            }}
+            document.querySelectorAll('img[data-fallback-src]').forEach(function(img){{
+                img.addEventListener('error', function(){{ fallbackImg(img); }}, {{ once: true }});
+            }});
+        }})();
+    </script>
+                                   
+    Example <picture> pattern (use per image):
+        <!-- Hidden inline SVG placeholder shown only if external images fail -->
+        <svg class="hidden w-full h-full object-cover" viewBox="0 0 1600 900" aria-hidden="true">
+            <defs>
+                <linearGradient id="grad" x1="0" y1="0" x2="1" y2="1">
+                <stop offset="0%" stop-color="#0a2540"/>
+                <stop offset="100%" stop-color="#001d2b"/>
+                </linearGradient>
+            </defs>
+            <rect width="1600" height="900" fill="url(#grad)"/>
+        </svg>
+        <picture>
+        <source srcset="https://images.unsplash.com/photo-1520607162513-77705c0f0d4a?w=1920 1920w" type="image/jpeg"/>
+            <img src="https://images.pexels.com/photos/3184292/pexels-photo-3184292.jpeg?auto=compress&w=1920"
+                alt="Team collaborating on AI product planning"
+                loading="lazy" decoding="async" referrerpolicy="no-referrer"
+                data-fallback-src="https://picsum.photos/seed/syntaxmatrix-hero/1920/1080"
+                onerror="this.onerror=null; this.dispatchEvent(new Event('error'));" />
+        </picture>
+        <picture>
+            <source srcset="https://source.unsplash.com/1600x900/?nature,water" media="(min-width: 800px)">
+            <source srcset="https://source.unsplash.com/800x600/?nature,water" media="(min-width: 400px)">
+            <img src="https://source.unsplash.com/400x300/?nature,water" alt="A beautiful scenery" loading="lazy" decoding="async" referrerpolicy="no-referrer">
+        </picture>
 
-    4. Style & Tone Guide (Negative Constraints):
-        DO NOT use conversational fillers ("Well," "So," "As you can see...").
-        DO NOT self-reference or mention that you are an AI.
-        DO NOT write long, unbroken paragraphs. Use lists, tables, and headings to break up the text.
-        PROCEED DIRECTLY to the answer without a preamble.
-"""
+    Animation snippet (include and reuse):
+    <script>
+        if(window.matchMedia('(prefers-reduced-motion: reduce)').matches){{
+        // Skip motion
+        }} else if(window.gsap && window.ScrollTrigger){{
+            gsap.registerPlugin(ScrollTrigger);
+            gsap.utils.toArray('.reveal').forEach(function(el){{
+                gsap.from(el, {{ 
+                    y: 24, opacity: 0, duration: 0.8, ease: 'power2.out',
+                    scrollTrigger: {{ trigger: el, start: 'top 80%' }} 
+                }});
+            }});
+            document.querySelectorAll('.counter').forEach(function(el){{
+                var t = parseInt(el.getAttribute('data-target'),10)||0, obj={{v:0}};
+                ScrollTrigger.create({{ 
+                    trigger: el, start: 'top 85%', once:true,
+                        onEnter: function(){{ 
+                            gsap.to(obj,{{ 
+                                v:t, duration:1.6, ease:'power2.out', onUpdate:function()  {{  
+                                    el.textContent = Math.round(obj.v); 
+                                }};
+                            }};
+                        }};
+                }});
+            }});
+        }};
+    </script>
+""")

syntaxmatrix/settings/string_navbar.py

@@ -1,5 +1,5 @@
 
 string_navbar_items = [
-            "Admin",
-            "Dashboard",           
-        ]
+        "Dashboard",     
+        "Admin",      
+    ]

syntaxmatrix/static/docs.md

@@ -0,0 +1,272 @@
+
+
+# SyntaxMatrix — Developer Guide
+---
+
+## Overview
+
+SyntaxMatrix focuses your app code on **logic** while it handles the chat UI, session state, file uploads, embeddings, and retrieval over two memories: **SMIV** (user uploads; per-session) and **SMPV** (system/company docs; persistent).
+
+- Session-aware chat history
+- Hybrid retrieval (user + system), or user-only, system-only, or none
+- Streaming and non‑streaming modes
+- Simple feature toggles in `settings.py`
+- Branding and site controls (logo, favicon, titles), theme + UI mode switches
+- Widgets (text input, buttons, dropdowns, uploader) and simple layout helpers
+
+---
+
+## Installation
+
+```bash
+pip install syntaxmatrix syntaxmatrix[mlearning,auth]
+```
+
+> Make sure your environment has any required API keys (e.g. OpenAI SDK compatible) available to your app.
+
+---
+
+## Quick start
+
+**settings.py** — feature flags & branding in one place
+```python
+from syntaxmatrix import (
+    enable_user_files, enable_stream, set_theme,
+    set_site_logo, set_site_title, set_project_name, set_favicon, set_user_icon,
+)
+
+enable_user_files()
+enable_stream()
+set_theme('light')  # available: light, dark, chark, github, solarized-light, solarized-dark, oceanic-next, ayu-mirage, one-dark
+
+# Branding (examples)
+set_site_logo("<img src='/static/logo.svg' style='height:22px;vertical-align:middle'>")
+set_site_title("SyntaxMatrix Demo")
+set_project_name("SyntaxMatrix Demo")  # used in nav & metadata
+set_favicon("<link rel='icon' href='/static/favicon.ico'>")
+set_user_icon("👤")
+```
+
+**app.py** — minimal consumer app
+```python
+import syntaxmatrix as smx
+from settings import *
+
+def create_conversation(stream=False):
+    chat = smx.get_chat_history() or []
+    sid = smx.get_session_id()
+    index = smx.smiv_index(sid)
+
+    query, intent = smx.get_text_input_value("user_query")
+    if not query: return
+    query = query.strip()
+    chat.append(("User", query))
+
+    # Retrieval (optional)
+    if intent == "none":
+        context, sources = "", []
+    else:
+        vec = smx.embed_query(query)
+        if vec is None: return
+        ctx, sources = [], []
+        if intent in ["hybrid","user_docs"]:
+            hits = index.search(vec, top_k=3) or []
+            ctx += ["\n### Personal Context (user uploads)\n"] + [f"- {{h['metadata']['chunk_text'].strip().replace('\\n',' ')}}\n" for h in hits]
+            if hits: sources.append("User Docs")
+        if intent in ["hybrid","system_docs"]:
+            sys = smx.smpv_search(vec, top_k=5) or []
+            if not sys: smx.error("Please contact support."); return
+            ctx += ["### System Context (company docs)\n"] + [f"- {{h['chunk_text'].strip().replace('\\n',' ')}}\n" for h in sys]
+            sources.append("System Docs")
+        context = "".join(ctx)
+
+    transcript = "\n".join([f"{{r}}: {{m}}" for r,m in chat])
+
+    if stream:
+        smx.stream_process_query(query, context, transcript, sources)
+    else:
+        ans = smx.process_query(query, context, transcript)
+        if isinstance(ans, str) and ans.strip():
+            if sources:
+                ans += "".join([f"<ul style='margin-top:5px;color:blue;font-size:0.8rem;'><li>{{s}}</li></ul>" for s in sources])
+            chat.append(("Bot", ans))
+
+    smx.set_chat_history(chat)
+    smx.clear_text_input_value("user_query")
+
+# UI widgets
+smx.text_input("user_query", "user_query", "Enter query", "Ask anything .")
+smx.button("submit_query","submit_query","Submit", lambda: create_conversation(smx.stream()))
+smx.file_uploader("user_files","user_files","Upload PDF files:", accept_multiple_files=True)
+
+def clear_chat(): smx.clear_chat_history()
+smx.button("clear_chat","clear_chat","Clear", clear_chat, stream=False)
+
+if __name__ == "__main__":
+    smx.run()
+```
+
+---
+
+## Full API surface (open-source)
+
+### App, theme, and UI
+```python
+smx.run()                                 # start the app
+smx.set_ui_mode(mode)                     # one of: default, bubble, card, smx
+smx.get_ui_modes()                        # → list of modes
+smx.set_theme(name)                       # one of: light, dark, chark, github, solarized-light, solarized-dark, oceanic-next, ayu-mirage, one-dark
+smx.get_themes()                          # → dict(name → colours)
+smx.enable_theme_toggle()                 # adds theme toggle to navbar
+smx.enable_user_files()                   # enables PDF uploader + SMIV
+smx.enable_stream()                       # enable streaming mode globally
+smx.stream()                              # returns True/False at runtime
+```
+
+### Branding & site identity
+```python
+smx.set_site_logo(html)                   # e.g. "<img src='/static/logo.svg' ...>"
+smx.set_site_title("Your Site Title")     # text next to the logo in navbar
+smx.set_project_name("Your Project")      # used in nav/meta contexts
+smx.set_favicon("<link rel='icon' href='/static/favicon.ico'>")  # raw <link> tag
+smx.set_user_icon("🙂")                    # icon used for user bubbles
+smx.set_website_description(text)         # used by /about and SEO meta
+```
+
+**Notes**
+- `set_site_logo` accepts **HTML** (so you can style the `<img>` inline).
+- `set_favicon` expects the full `<link ...>` element; store your icon in `/static/` and reference it there.
+
+### Widgets & layout
+```python
+smx.text_input(key, id, label, placeholder)       # register a text box
+text, intent = smx.get_text_input_value(id)       # returns (string, intent)
+
+smx.button(key, id, label, callback, stream=False)
+smx.clear_text_input_value(id)
+
+smx.file_uploader(key, id, label, accept_multiple_files=True)
+files = smx.get_file_upload_value(id)             # list-like (optional use)
+
+smx.dropdown(key, options, label=None, callback=None)
+value = smx.get_widget_value(key)                 # read current selection
+
+html = smx.columns([left_html, right_html])       # simple two+ column layout
+```
+
+### Sessions & history
+```python
+sid = smx.get_session_id()
+hist = smx.get_chat_history()
+smx.set_chat_history(hist or [])
+smx.clear_chat_history()
+```
+
+### Retrieval & embeddings
+```python
+vec = smx.embed_query(query)                      # → embedding vector
+idx = smx.smiv_index(sid)                         # session index (SMIV)
+hits = idx.search(vec, top_k=3)                   # user uploads
+sys_hits = smx.smpv_search(vec, top_k=5)          # system/company docs
+
+# Pre-load system PDFs (optional, e.g. on startup)
+smx.load_sys_chunks("uploads/sys")                # populates in-memory cache
+```
+
+### Answering (streaming & non-streaming)
+```python
+smx.stream_process_query(query, context, conversations, sources)
+smx.process_query(query, context, conversations)  # → str
+smx.process_query_stream(query, context, conversations)  # alt helper
+smx.get_stream_args()                             # read any stream args (advanced)
+```
+
+### Prompt & profile helpers
+```python
+smx.set_prompt_profile(purpose="chat", profile_name="default")  # select profile
+smx.set_prompt_instructions("You are ...")                      # set system text
+
+# Embed model record (provider/model/key) stored encrypted in local DB:
+smx.save_embed_model(provider="openai", model="gpt-5-mini", api_key="sk-...")
+cfg = smx.load_embed_model()                                    # → dict
+smx.delete_embed_key()                                          # wipe stored key
+```
+
+> Behind the scenes, profiles/keys live in a local SQLite DB (encrypted API key via Fernet).
+
+### Advanced: Flask app access
+```python
+app = smx.app                         # access underlying Flask app
+@app.route("/docs")
+def docs_alias():
+    from flask import redirect, url_for
+    return redirect(url_for('view_page', page_name='docs'))
+```
+
+---
+
+## Theming and UI modes
+
+- **Themes:** light, dark, chark, github, solarized-light, solarized-dark, oceanic-next, ayu-mirage, one-dark
+  ```python
+  smx.set_theme('github')
+  smx.enable_theme_toggle()
+  ```
+
+- **UI modes:** default, bubble, card, smx
+  ```python
+  smx.set_ui_mode('bubble')  # try 'card' for boxy chat, or 'smx' for framework default
+  ```
+
+---
+
+<!-- ## Professional Docs page (Shadow DOM)
+
+Paste this into **/admin → Edit Page → docs**. It renders `/static/docs.md` inside a Shadow DOM with its own CSS, so global CSS can’t distort it.
+
+```html
+<div id="syntaxmatrix-docs-root"></div>
+<script>
+(function () {{
+  const host = document.getElementById('syntaxmatrix-docs-root');
+  const shadow = host.attachShadow({{ mode: 'open' }});
+  shadow.innerHTML = `
+    <style>
+      :host {{ all: initial; }}
+      .doc {{ box-sizing:border-box; max-width: 980px; margin: 0 auto; padding: 24px;
+              color:#1b1f23; background:#fff; font: 16px/1.6 system-ui,-apple-system,Segoe UI,Roboto,Ubuntu,Cantarell,Helvetica,Arial,Noto Sans,sans-serif; }}
+      .doc * {{ box-sizing: inherit; text-align: left; }}
+      .doc h1 {{ font-size: 2rem; margin: 0 0 .75rem }}
+      .doc h2 {{ margin-top: 2rem; padding-bottom: .4rem; border-bottom: 1px solid #e1e4e8; }}
+      .doc h3 {{ margin-top: 1.25rem; }}
+      .doc p, .doc li {{ line-height: 1.65; }}
+      .doc ul, .doc ol {{ padding-left: 24px; }}
+      .doc blockquote {{ border-left: 4px solid #e1e4e8; margin: 1rem 0; padding: .25rem 1rem; color: #586069; background: #fafbfc; }}
+      .doc code, .doc pre {{ font-family: ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,'Liberation Mono','Courier New',monospace; }}
+      .doc pre {{ white-space: pre; background:#f6f8fa; border:1px solid #e1e4e8; padding:12px; border-radius:8px; overflow:auto; position: relative; }}
+      .copy-btn {{ position:absolute; top:8px; right:8px; border:1px solid #e1e4e8; background:#fff; padding:2px 8px; border-radius:6px; font-size:.8rem; cursor:pointer; }}
+      .doc table {{ border-collapse: collapse; width: 100%; }}
+      .doc th, .doc td {{ border:1px solid #e1e4e8; padding:6px 10px; vertical-align: top; }}
+      .doc img {{ max-width:100%; height:auto; }}
+      .doc .note {{ background:#f6f8fa; border:1px solid #e1e4e8; padding:10px 12px; border-radius:8px; }}
+    </style>
+    <article class="doc"><p class="note">Loading documentation…</p></article>
+  `;
+  const container = shadow.querySelector('.doc');
+  const mk = document.createElement('script');
+  mk.src = 'https://cdn.jsdelivr.net/npm/marked/marked.min.js';
+  mk.onload = () => {{ fetch('/static/docs.md', {{ cache: 'no-cache' }}) 
+    .then(r => r.text())
+    .then(md => {{ container.innerHTML = window.marked.parse(md); addCopyButtons(); }})
+    .catch(() => {{ container.innerHTML = '<p style="color:#b00">Could not load <code>static/docs.md</code>.</p>'; }}); }};
+  shadow.appendChild(mk);
+  function addCopyButtons() {{ shadow.querySelectorAll('pre > code').forEach(code => {{
+    const btn = document.createElement('button'); btn.className = 'copy-btn'; btn.textContent = 'Copy';
+    btn.addEventListener('click', () => {{ navigator.clipboard.writeText(code.textContent || ''); btn.textContent = 'Copied'; setTimeout(() => btn.textContent='Copy', 900); }});
+    code.parentElement.appendChild(btn);
+  }}); }}
+}})();
+</script>
+``` 
+Upload your Markdown as `static/docs.md` and you’re done. 
+-->