Document chat-first client workspaces, campaign review and scoped Hermes learning

BuxUp_System_Plan.md

@@ -0,0 +1,277 @@
+# BuxUp Growth Desk
+
+## One client. One workspace. Every campaign connected.
+
+A chat-first campaign workspace for payment providers. Start with a client domain, documents, or a conversation. Hermes researches that provider, builds a reusable knowledge base, prepares platform-specific campaigns, and brings the evidence and review questions back to a person before anything is published.
+
+**Working system plan · Version 2 · 2 November 2026**
+
+This is the proposed product experience and architecture, ready to read and extend. The diagrams and workspace previews explain the planned system; they are not connected to live client records or model inference on this documentation page.
+
+## 01 — The business and the people
+
+The paying client is a payment provider, EMI, PSP, merchant acquirer, or a related financial-services company. The audience is a business that might need that provider’s services: for example, an importer seeking cross-border payments or a merchant looking for acquiring services. BuxUp helps the provider reach suitable businesses and prepare campaigns that its team can review efficiently.
+
+The operator manages the client and campaign. The client’s designated reviewer checks the proposed material and resolves questions about claims, eligibility, and applicable requirements. Hermes coordinates research, drafting, images, analysis, and scoped memory. The application backend controls access, records, jobs, and approval state.
+
+The goal is qualified interest in an offering the provider actually supports. More clicks alone do not show that the right merchants are being reached. The public brochure website can stay separate from this client workspace.
+
+## 02 — Start in chat, create a client workspace
+
+The user begins in a general intake chat and enters the client’s domain, uploads documents or images, pastes information, or combines those inputs. A domain can be enough to start research; it is not automatically enough to approve an offer or launch a campaign.
+
+1. Resolve the provider’s identity and suggest an existing workspace if that domain already belongs to a known client. A domain is a discovery hint, not proof of identity or ownership.
+2. Create a separate client workspace with a stable client ID, client name, domain aliases, access permissions, and an intake record.
+3. Place the chat, uploaded files, extracted facts, source links, and research tasks inside that client’s context.
+4. Browse official client pages for services, features, offers, eligibility conditions, geographic coverage, and brand information. Supplement with clearly attributed external sources when useful.
+5. Show the user what was found, which facts conflict, and what still needs confirmation. Ask focused questions rather than inventing missing terms.
+
+An example first message is: “Here is example-provider.com and our product brochure. Create a workspace and help us promote the cross-border payment offering.” The domain is illustrative; it is not a real client in this guide.
+
+```mermaid
+%% diagram: journey
+flowchart LR
+  A[Domain, files or chat] --> B[Separate client workspace]
+  B --> C[Research and source-backed profile]
+  C --> D[Campaign brief and locations]
+  D --> E[Platform copy and images]
+  E --> F[Jurisdiction and claim review]
+  F --> G[Human approval of exact version]
+  G --> H[Campaign history and learning]
+```
+
+## 03 — Inside one client’s space
+
+Each payment provider has its own chat and files. Once a workspace is selected, the conversation is about that provider. The interface should make the current client and campaign visible so a user can see which context their instruction changes.
+
+A client space is a separate area inside BuxUp, not a new Hugging Face deployment for every provider. Its isolation is enforced by client IDs and permissions throughout the application.
+
+| Area | What lives there | How it is used |
+| --- | --- | --- |
+| Client chat | Questions, corrections, decisions, attachments, and requests | Add facts, remove claims, change tone, or start work for this provider |
+| Knowledge | Products, features, accepted sectors, exclusions, approved facts, and evidence | Supply reusable context without re-researching everything |
+| Files and sources | PDFs, images, text, website references, extraction records, and versions | Trace facts back to their source and manage replacements |
+| Campaigns | Each offering, brief, platform variants, visuals, and review status | Keep campaign work separate while reusing the client profile |
+| Client memory | Confirmed preferences, recurring corrections, and reviewer feedback | Make the next campaign more relevant to this provider |
+| Review and history | Approvals, rejected versions, comments, and results | Explain what happened, who decided, and what was learned |
+
+“Remove that offer,” “add this file,” “forget the old pricing,” and “use a more formal voice” are supported intents in the planned chat. A file deletion or factual correction needs a concrete change summary, especially if it affects current campaigns. The original chat message alone is not the database update.
+
+Removing a source also invalidates its extracted chunks and dependent memory or claims. Show affected campaigns and mark them for another check. Permission and retention rules determine whether an old approval record can retain limited audit metadata; removed source content must not remain silently available in retrieval.
+
+```mermaid
+%% diagram: client
+flowchart TD
+  A[One provider workspace / client_id] --> B[Client chat]
+  A --> C[Knowledge and evidence]
+  A --> D[Campaigns]
+  B --> E[Files / add / replace / remove]
+  C --> F[Client memory and confirmed facts]
+  D --> G[Versions / reviews / outcomes]
+  F --> D
+```
+
+## 04 — When does Hermes know enough?
+
+Research starts immediately, but readiness is a visible checklist. The application distinguishes **found on the web**, **provided by the user**, **confirmed by a reviewer**, **inferred**, **conflicting**, and **expired** information. Public marketing text is evidence of what a website says, not automatic proof that every claim is usable in a new advertisement.
+
+Before preparing a useful campaign pack, establish the provider, the specific offering, the audience, target locations, campaign objective, chosen platforms, proposed call to action, available evidence, and the person responsible for review. If material facts are missing, Hermes can create a clearly marked provisional draft and list its assumptions. It must not silently fill in rates, eligibility, authorisation status, or guarantees.
+
+Save each important fact with its source, date checked, status, and the product or geography it applies to. Offers, prices, availability, and time-limited promotions get an expiry or recheck date. For contradictory sources, preserve the disagreement and ask for a decision.
+
+A client profile is reused, but not trusted forever. On the next campaign, refresh only stale or relevant facts first: an expired offer, a changed product page, a new target state, a replaced brochure, or a new requirement. This avoids repeating the whole discovery process while still checking what may have changed.
+
+## 05 — Start a new campaign without starting over
+
+Inside the client workspace, the user can type “start a new campaign” or select a **New campaign** button. The new campaign receives its own ID and thread, then loads the approved client profile, relevant source material, previous decisions, and applicable geographic knowledge.
+
+The user supplies what has changed: “Promote this new offering,” “use this seasonal offer,” “target importers in this country,” or “make LinkedIn, Instagram, and TikTok versions.” Hermes summarizes the brief and unresolved questions before creating the pack.
+
+1. Choose the offering, audience, objective, call to action, platforms, language, and country/state/province.
+2. Retrieve the client’s relevant knowledge and previous campaign lessons. Filter history by product, audience, location, and recency.
+3. Check the freshness of offer details and retrieve anything genuinely new.
+4. Research campaign angles, produce platform-specific copy and visual briefs, then request the required images.
+5. Run a separate evidence and jurisdiction review on the actual copy, visual content, audience, placement, and destination page.
+6. Present the pack, flagged passages, proposed revisions, source links, and unknowns to the user.
+7. Wait for the designated human’s decision. Revisions produce a new version and trigger the relevant checks again.
+8. Record approved exports or a separately authorised publication action, then capture available results and feedback.
+
+There is no default autonomous ad publishing or budget change. Approval of a draft and permission to spend money or publish through an ad account are distinct actions.
+
+## 06 — A different creative for each platform
+
+The core offer remains consistent, but the copy, composition, and visual brief change with the platform and placement. Each variant is a linked campaign artifact with its own version and review status. An image with text in it is part of the message being reviewed.
+
+| Platform | Planned copy and image treatment | What the reviewer sees |
+| --- | --- | --- |
+| TikTok | A concise hook, short on-screen message, caption, call to action, and a vertical creative or storyboard | The hook, visible claims, caption, image, and any missing video production work |
+| Instagram | Visual-led headline, caption, call to action, and placement-specific image variants | The full visual, readable conditions, copy, and destination link |
+| LinkedIn | A business-focused problem, relevant provider capability, professional copy, and a supporting visual | The audience fit, factual support, professional tone, and image/copy combination |
+
+These are creative directions, not fixed platform specifications. Check current placement dimensions, file requirements, and platform advertising policies before export. Generating a still image does not by itself produce a finished TikTok video.
+
+Illustrative creative previews on this page use a fictional provider and editorial vector art. They demonstrate different compositions; they are not model-generated campaign results, verified offers, or approved advertisements.
+
+<!-- creative-previews -->
+
+![Illustrative TikTok creative](assets/creative-tiktok.svg)
+
+![Illustrative Instagram creative](assets/creative-instagram.svg)
+
+![Illustrative LinkedIn creative](assets/creative-linkedin.svg)
+
+## 07 — The proxy and model roles
+
+The selected inference gateway is the existing [gravityyy-proxyyy Space](https://huggingface.co/spaces/bardd/gravityyy-proxyyy). Its published source exposes an OpenAI-compatible chat endpoint and supports web-search tool conversion and returned grounding citations. The health endpoint responded successfully during this review; the model listing requires authentication.
+
+| Role | Requested route | Planned responsibility | Verification status |
+| --- | --- | --- | --- |
+| Main reasoning and coordination | `gemini-3.8-flash-tiered` | Chat, research, client profiling, campaign briefs, copy, analysis, and review orchestration | User-selected proxy route; authenticated availability and end-to-end behavior still need a capability check |
+| Image creation | `gemini-3.1-flash-lite` | Produce campaign images from platform-specific visual briefs and permitted references | User-requested route; actual image output must be verified, not inferred from image-input support |
+| Multimodal reading | A confirmed vision/document-capable route through the proxy | Extract information from images and PDFs, with OCR or page rendering where needed | Exact route, supported input representation, document limits, and extraction quality need testing |
+| Web-grounded review | Main model with an explicitly enabled search tool | Find source material, retain citations, and research the campaign’s geographic requirements | Source includes search-tool and citation handling; live behavior must be tested with the configured route |
+
+Preserve these requested route names in configuration. A proxy alias can map to another upstream model, so record both the requested route and resolved model when available. If an image call returns only text or the proxy cannot preserve image output, show an unavailable state and select a verified image-capable route explicitly; do not display a text answer as an image.
+
+Google’s current [image-generation documentation](https://ai.google.dev/gemini-api/docs/image-generation) lists `gemini-3.1-flash-lite-image` as an image model. That is distinct from the requested proxy alias `gemini-3.1-flash-lite`; whether your alias maps to image generation has not been established here. Its [search documentation](https://ai.google.dev/gemini-api/docs/google-search) describes enabling grounding tools and retaining returned sources.
+
+Requests belong on the backend. The browser communicates with BuxUp; BuxUp’s backend calls the proxy with server-held credentials. The public guide and browser bundle must not contain a proxy API key. Source inspection is not a claim that live inference, PDF extraction, or image generation has been implemented in this guide.
+
+## 08 — A separate research and compliance-review pipeline
+
+After drafting, run a separate review task with the campaign’s exact artifacts, source-backed offer details, audience, target locations, and platform. Its purpose is to tell the reviewer **where to look and what may need changing**. A second model call is another review step, not an independent legal authority.
+
+Determine the product and audience before choosing a ruleset. A generic banking, investment, or crypto checklist should not be applied to every payment-services campaign. Keep provider acceptance restrictions, applicable legal/regulatory material, platform policies, and the client’s internal policies distinguishable.
+
+For each potential issue, return the exact copy or visual element, the relevant rule or policy and authoritative link, the jurisdiction, why it may apply, the evidence or missing information, the date checked, uncertainty, a proposed edit, and the question for the human reviewer. Prefer official legislation, regulator publications, and current platform policy sources. A search snippet is not enough to substantiate a legal conclusion.
+
+| Review field | Example structure, not an actual legal finding |
+| --- | --- |
+| Artifact | Instagram image v2, headline text |
+| Flagged statement | “Instant approval for every business” |
+| Issue | The provider’s evidence does not establish that universal claim |
+| Location | Selected country and any relevant state/province |
+| Source | Provider evidence plus the applicable official rule or platform policy, with a direct link |
+| Reviewer question | Can this claim be substantiated for this audience and offering? |
+| Proposed action | Qualify the wording or remove the claim; check the revised image and caption together |
+
+Return “potential issue,” “needs evidence,” “scope uncertain,” or “review needed,” with reasons. Do not label a generated pack “legally compliant” or treat a disclaimer as a substitute for determining the correct review and approval requirements. For the UK, the [FCA’s overview](https://www.fca.org.uk/firms/financial-promotions-adverts) is one starting point; product-specific applicability still needs checking.
+
+The designated reviewer sees both the proposed material and the research. A decision records reviewer identity, timestamp, comments, and exact artifact versions. Changes to a claim, image, offer, location, targeting, or destination page invalidate the affected approval and require another review. The required reviewer roles and approval process are configured for the client and jurisdiction, rather than assumed universal.
+
+## 09 — Hermes: how the agent actually works
+
+Hermes is the coordinating agent layer, not the model, the database, or the proxy itself. It receives a scoped task, chooses approved tools, loads relevant memory, executes the work, and returns artifacts and evidence to the application. The backend remains the source of truth for client boundaries and approval state.
+
+Every task carries a client ID, campaign ID when relevant, user permissions, target jurisdictions, selected model route, and a limited tool budget. Research, document extraction, drafting, image generation, and review can be separate jobs. A failed job is retried or surfaced without losing the campaign’s history.
+
+```mermaid
+%% diagram: agent
+flowchart LR
+  A[Scoped user instruction] --> B[Load permitted context]
+  B --> C[Plan the task]
+  C --> D[Call research / model / file tools]
+  D --> E[Store artifacts and evidence]
+  E --> F[Human review]
+  F --> G[Record feedback]
+  G --> H[Update scoped memory]
+  H --> B
+```
+
+The context builder loads only the selected client’s active records, campaign history that is relevant to the task, applicable geographic knowledge, and approved global skills. Retrieved website content and uploaded files are evidence to inspect, not instructions that can change permissions, reveal another client’s files, or publish a campaign.
+
+Agent memory should live in a durable store with scope and version metadata. It is not merely a growing chat transcript, and it does not imply changing a model’s weights. The proposed first implementation learns through reusable facts, retrieval, preferences, prompts, and versioned skills.
+
+## 10 — Three learning scopes, kept distinct
+
+Hermes learns at the client level, the geographic level, and the global level. The application decides where each memory belongs and which future tasks may use it.
+
+| Scope | What Hermes can retain | Example | Boundary |
+| --- | --- | --- | --- |
+| Client learning | That provider’s confirmed products, voice, accepted claims, reviewer preferences, exclusions, and campaign corrections | “This provider’s reviewer prefers this wording and rejected that unsupported promise” | Visible only to authorised work for this client |
+| Geographic learning | Sourced research, applicability notes, effective dates, and review outcomes for a country and relevant subdivisions | “Recheck this source when targeting this state and product category” | Reusable only for matching scope; never a timeless universal legal rule |
+| Global learning | General workflow improvements and non-confidential skills that help all clients | “Before drafting a time-limited offer, check its expiry and required evidence” | Promote a general lesson without another client’s identity, private offer, files, or sensitive data |
+
+The geographic hierarchy is **country → state/province/region where relevant → product and audience applicability**. For example, US-wide material and California-specific material can coexist; the system retrieves the relevant combination rather than assuming the state replaces all national requirements. Where no regional distinction is relevant, the extra level can remain empty.
+
+```mermaid
+%% diagram: learning
+flowchart LR
+  A[Campaign feedback] --> B[Private client memory]
+  B --> C[Next campaign for this client]
+  A --> D[Candidate general lesson]
+  D --> E[Remove client details / check scope]
+  E --> F[Geographic knowledge or global skill]
+  F --> G[Version / evaluate / activate]
+  G --> C
+```
+
+Hermes can update client-scoped memory from confirmed user instructions and recorded feedback. It can also propose and maintain shared knowledge and global skills. Changes that affect all clients or change decision rules should pass scope checks, evaluation, versioning, and the configured activation policy; material policy or code changes require owner review. This allows learning without silently changing every client’s behavior.
+
+Each memory has a scope, source, creation date, validity or recheck date, confidence/status, and version. A reviewer can inspect, correct, remove, or roll it back. A single rejected campaign is useful feedback, but not automatically a general rule or evidence of a performance improvement.
+
+## 11 — The architecture and stored records
+
+The frontend provides general intake, client switching, client chat, files, campaign variants, source inspection, and review. A backend authenticates the user, enforces client access, stores the records, queues work, and calls Hermes and the model proxy. Files and generated media belong in persistent file storage; searchable knowledge and campaign metadata belong in durable stores.
+
+```mermaid
+%% diagram: architecture
+flowchart LR
+  A[Chat and review interface] --> B[BuxUp application backend]
+  B --> C[Hermes task coordinator]
+  C --> D[Authenticated model proxy]
+  D --> E[Main / multimodal / image routes]
+  B --> F[Client records and file storage]
+  C --> G[Scoped memory and evidence]
+  G --> C
+```
+
+| Record | Essential fields |
+| --- | --- |
+| Client | client_id, canonical domain, aliases, profile, access roles, confirmed facts |
+| Source or file | client_id, source_id, URL/file reference, type, version, extracted chunks, checked date, deletion status |
+| Campaign | client_id, campaign_id, offering, brief, audience, jurisdictions, platforms, objective, status |
+| Artifact | campaign_id, platform, copy/image/file reference, version, sources, model route, creation time |
+| Review finding | artifact version, flagged element, source, jurisdiction, rationale, uncertainty, suggested action |
+| Approval | exact artifact versions, reviewer, decision, timestamp, comments, invalidation state |
+| Memory | client/geographic/global scope, applicability, evidence, validity, version, activation state |
+| Run | job ID, scoped task, tool/model calls, status, errors, cost/usage when available |
+
+Client isolation is an access and retrieval rule enforced by the backend, not just a separate folder name. The chat, file search, memory retrieval, job queue, and generated assets all need the same client boundary. Geography is a knowledge scope, not permission to share private client data.
+
+Credentials stay server-side; only the authorised backend calls the proxy. External research fetches should accept public web destinations, block private/internal network targets, and treat downloaded material as untrusted. Jobs need clear progress, cancellation, bounded retries, and resumable state so a failed image call does not lose the rest of a campaign.
+
+## 12 — The next campaign remembers the useful parts
+
+Imagine campaign one introduced a provider’s cross-border payment service. The client corrected its supported countries, removed a fast-onboarding claim, preferred a restrained visual style, and approved a revised LinkedIn variant. Those facts and decisions are stored with their scope and evidence.
+
+Weeks later, the user selects the same client and starts a campaign for a different offering. Hermes already knows the confirmed provider profile and relevant brand preferences. It asks about the new offering and target audience, checks that any reused facts remain current, and pulls only lessons applicable to this product and location.
+
+If the new campaign targets a different state or country, Hermes loads that geographic context and rechecks applicability. Previous approval does not transfer automatically to a different ad, offer, audience, platform, or jurisdiction. The earlier campaign is helpful history, not blanket permission.
+
+This is the intended experience: **start with existing knowledge, ask only for what changed, create new versions, and make the reasoning visible.**
+
+## 13 — What to build first, and how to judge it
+
+The first pilot should demonstrate the whole path in one provider workspace: domain/document intake, grounded profile, reusable client chat, one campaign with different platform drafts and images, cited review questions, exact-version human approval, and a second campaign that reuses the right history. Keep the first live market and offering narrow even though the architecture supports more locations and clients later.
+
+1. **Capability checks:** verify the authenticated main route, real search citations, one image/PDF extraction, and actual image output through the proxy. Store results and explicit unavailable states.
+2. **Client foundation:** build intake, stable client identity, isolated chat, file add/remove, research evidence, and a profile confirmation step.
+3. **Campaign loop:** add New campaign, platform-specific drafting, images, scoped legal/policy research, revision handling, and approval capture.
+4. **Reuse test:** run a second campaign for the same client. Confirm that relevant context is reused, expired facts are refreshed, and unrelated client information is absent.
+5. **Learning rollout:** retain client feedback from day one, then evaluate geographic and global lessons before activating changes broadly.
+
+Measure preparation time, reviewer effort, revision count, factual corrections, quality of citations, proportion of claims with evidence, context reuse, and cross-client isolation. If a live campaign runs, also measure eligible inquiries and provider feedback; early clicks alone are not proof of acquisition value.
+
+Open decisions to fill in next: the first provider, exact offering, initial country or state, reviewer roles, publishing permissions, image-route mapping, document limits, approved research sources, memory retention, budget, and the pilot’s success thresholds.
+
+## Sources and review notes
+
+- [Existing BuxUp Space](https://huggingface.co/spaces/bardd/BuxUp): the earlier business concept and architecture guide.
+- [Proxy README](https://huggingface.co/spaces/bardd/gravityyy-proxyyy/blob/main/README.md): chat endpoints and server-side bearer authentication.
+- [Proxy OpenAI request conversion](https://huggingface.co/spaces/bardd/gravityyy-proxyyy/blob/main/src/format/openai-compat.js): image-input and search-tool handling in the published source.
+- [Proxy grounding support](https://huggingface.co/spaces/bardd/gravityyy-proxyyy/blob/main/src/format/grounding.js): returned source URLs and citation annotations.
+- [Google image generation](https://ai.google.dev/gemini-api/docs/image-generation) and [search grounding](https://ai.google.dev/gemini-api/docs/google-search): upstream capability references, not proof of a proxy alias’s live behavior.
+- [FCA financial promotions overview](https://www.fca.org.uk/firms/financial-promotions-adverts): a starting source for relevant UK research; this guide contains no campaign-specific legal determination.
+
+Review date: 2 November 2026. Proxy source and health were inspected; authenticated inference, image generation, PDF extraction, and production campaign execution were not tested as part of this documentation update.