Upload 2 files

docs/product_readme_viral_muse.md

@@ -0,0 +1,68 @@
+# product_readme.md
+[AGENTARIUM_ASSET]
+Name: Viral Muse – Product Readme / Listing
+Version: v1.0
+Status: Draft
+
+## Title
+Viral Muse — Music Pattern Architect (TikTok-Ready Concept Builder)
+
+## Short Tagline
+A pattern-first creative partner for artists: hooks, structures, TikTok formats, and genre flips — guided by datasets, not “lyric bot vibes.”
+
+## What it is
+**Viral Muse** is an Agentarium-style agent package designed to help creators develop **viral-but-original** music concepts.
+It works by reasoning over structured pattern libraries (datasets) and returning **clear creative direction**: hooks, sections, constraints, and format-first ideas.
+
+This package is ideal if you want:
+- repeatable ideation (not random inspiration)
+- consistent structure (not messy brainstorming)
+- TikTok-native formats + genre transformation logic
+
+## What it does (capabilities)
+- Generates **song concept blueprints**: hook idea, section plan, arc, replay triggers
+- Suggests **TikTok content formats**: openers, framing, loop mechanics, “what to film”
+- Applies **genre transformations**: translate the same concept into different genres while keeping the “core payload”
+- Uses a **viral signal checklist** to score and strengthen ideas without copying trends
+- Provides **creative partner advice**: what to simplify, what to exaggerate, what to test
+
+## What’s included (Agentarium v1 core)
+- `/meta/agent_manifest.json`
+- `/core/system_prompt.md`
+- `/core/reasoning_template.md`
+- `/core/personality_fingerprint.md`
+- `/guardrails/guardrails.md`
+- `/docs/workflow_notes.md`
+- `/docs/use_cases.md`
+- `/datasets/` (6 CSV datasets)
+  - `lyric_structure_map.csv`
+  - `viral_pattern_detector.csv`
+  - `genre_transformation_rules.csv`
+  - `tiktok_concept_patterns.csv`
+  - `viral_potential_rater.csv`
+  - `creative_partner_advice_map.csv`
+- `/memory_schemas/` (user profile + project workspace)
+  - `user_profile_memory.csv`
+  - `project_workspace_memory.csv`
+  - `memory_rules.md`
+
+## Ideal buyers
+- musicians + producers building a repeatable writing pipeline
+- creator teams making TikTok-first music content
+- AI builders who want a **dataset-driven** creative agent template
+- indie labels / A&R experiments (concept validation + testing loops)
+
+## How to use (high level)
+1) Load the system prompt + reasoning + personality into your agent runtime.
+2) Upsert datasets into a vector DB (or keep as local retrieval index).
+3) Ask for **concepts**, not final lyrics:
+   - “Give me 5 hook angles for X vibe”
+   - “Design a 30s TikTok loop concept for…”
+   - “Transform this concept into afrobeat / reggaeton / alt rock”
+
+## Notes
+- This is a **pattern architect**, not a plagiarism machine.
+- Outputs are intentionally structured and testable (multiple variants + constraints).
+
+## License / attribution
+Use whatever license you set in the manifest. Recommended: CC BY 4.0 for open distribution, or a commercial license for paid bundles.

docs/workflow_notes_viral_muse.md

@@ -0,0 +1,193 @@
+# workflow_notes.md
+[AGENTARIUM_ASSET]
+Name: Viral Muse – Workflow Notes (Implementation)
+Version: v1.0
+Status: Draft
+
+## Goal
+Implement Viral Muse as a **dataset-driven** agent using:
+- system prompt + reasoning template + personality fingerprint
+- guardrails
+- RAG over the 6 CSV datasets
+- optional “knowledge map” layer for cross-dataset linking
+- memory: user profile + project workspace
+
+This guide assumes an orchestration runtime like **n8n**, but the logic applies to LangChain, Flowise, Dify, etc.
+
+---
+
+## 0) Folder sanity check (Agentarium v1)
+You should have:
+- `/core/` (system_prompt.md, reasoning_template.md, personality_fingerprint.md)
+- `/datasets/` (6 CSVs)
+- `/guardrails/guardrails.md`
+- `/memory_schemas/` (2 CSV schemas + memory_rules.md)
+- `/docs/` (this file + readme + use cases)
+
+If you add a knowledge map later, put it in:
+- `/datasets/knowledge_map.csv` (recommended) or `/datasets/master_grid.csv`
+
+---
+
+## 1) Implement the core behavior files
+### 1.1 System Prompt
+- Paste `/core/system_prompt.md` into your agent’s **system** message.
+- This defines the agent’s role: pattern-first creative partner.
+
+### 1.2 Reasoning Template
+- Store `/core/reasoning_template.md` as internal guidance in your runtime (developer message / hidden instruction / “policy doc”).
+- Your runtime should prepend it before each completion (or inject as a “rules” section).
+
+### 1.3 Personality Fingerprint
+- Add `/core/personality_fingerprint.md` as a style constraint layer.
+- Use it to keep tone consistent: compact, direct, pattern-oriented.
+
+**Result:** the model behaves consistently even before RAG.
+
+---
+
+## 2) Apply guardrails
+- Load `/guardrails/guardrails.md` as a rules block.
+- Enforce:
+  - no plagiarism / no “copy this hit song” behavior
+  - no made-up dataset facts
+  - no unsafe content requests
+  - outputs should be structured and testable
+
+In n8n: you typically inject guardrails as part of the prompt assembly (before the user message).
+
+---
+
+## 3) Prepare datasets for RAG
+You have 6 CSV datasets in `/datasets/`.
+Best practice is to convert each row into a **retrieval document** with:
+- `source_dataset`
+- `row_id`
+- key fields
+- a short “row summary” string for embeddings
+
+### 3.1 Minimal row-to-document format (recommended)
+For each CSV row, create a text payload like:
+
+- Title line: `[DATASET=lyric_structure_map | id=LSM_012]`
+- Then: `field=value` lines (only the meaningful ones)
+- Then: a compact 1–2 sentence row summary
+
+This makes retrieval clean and avoids embedding empty columns.
+
+---
+
+## 4) Upsert into a Vector DB (VDB)
+You can use Pinecone, Qdrant, Weaviate, Chroma, FAISS — anything that supports:
+- embeddings vector
+- metadata filters
+- similarity search
+
+### 4.1 What to store per vector
+**Vector record**
+- `id`: stable id (ex: `lyric_structure_map:LSM_012`)
+- `text`: the row-to-document payload
+- `metadata`:
+  - `dataset` (one of the 6)
+  - tags / genre / pattern_type (if available)
+  - any fields you want to filter by
+
+### 4.2 n8n implementation (practical steps)
+1) **Read file(s)**
+   - Node: “Read Binary File” (or fetch from GitHub / Drive)
+2) **Parse CSV**
+   - Node: “Spreadsheet File” → Convert to JSON (or CSV Parse)
+3) **Normalize rows**
+   - Node: “Function” (build `id`, `text`, `metadata`)
+4) **Create embeddings**
+   - Node: “OpenAI” → Embeddings (or any embedding provider)
+5) **Upsert to VDB**
+   - Pinecone/Qdrant/Weaviate via:
+     - native node if available, OR
+     - “HTTP Request” node to the VDB REST API
+6) **Verify**
+   - Run a test query and confirm you retrieve relevant rows.
+
+**Tip:** store dataset name in metadata so you can filter retrieval per task:
+- “only TikTok formats” → filter dataset=`tiktok_concept_patterns`
+- “structure help” → dataset=`lyric_structure_map`
+
+---
+
+## 5) RAG retrieval at runtime
+At inference time, your agent should:
+1) classify intent (hook / structure / tiktok / genre flip / audit)
+2) select 1–3 datasets to query
+3) retrieve top-K rows (ex: K=6–12)
+4) synthesize output using retrieved rows only (no invented dataset claims)
+
+### 5.1 Prompt assembly (runtime order)
+1) System prompt
+2) Guardrails
+3) Reasoning template
+4) Personality fingerprint
+5) Memory snapshot (user profile + project workspace)
+6) Retrieved context (RAG)
+7) User message
+
+---
+
+## 6) Knowledge map / “Master Grid” (optional but recommended)
+If you want cross-dataset reasoning, add a **knowledge map** file to link patterns:
+
+### 6.1 Simple schema (CSV)
+Store links as triplets:
+- `source_node`, `relation`, `target_node`, `weight`, `notes`
+
+Examples:
+- `tiktok_format:duet_bait` → `supports` → `viral_signal:comment_trigger`
+- `structure:prechorus_lift` → `amplifies` → `viral_signal:anticipation`
+- `genre_flip:reggaeton` → `prefers` → `hook_style:call_response`
+
+### 6.2 How to use it
+- Upsert the knowledge map into the same VDB (or keep as a small local lookup table).
+- When generating, retrieve:
+  - primary rows from the relevant dataset(s)
+  - plus 3–8 knowledge-map links that connect them
+- Use those links to produce “why this works” explanations and better constraints.
+
+---
+
+## 7) Memory implementation (User Profile + Project Workspace)
+Use the files in `/memory_schemas/`:
+- `user_profile_memory.csv`
+- `project_workspace_memory.csv`
+- `memory_rules.md`
+
+### 7.1 Read memory
+Before responding:
+- load active user profile facts (preferences, style constraints)
+- load current project workspace (objectives, constraints, next actions)
+
+### 7.2 Write memory
+After responding, write only durable facts:
+- user preferences that recur
+- project decisions (selected concept, chosen genre, chosen structure)
+- next actions (what to test next)
+
+**Important:** append new rows; don’t overwrite old ones.
+
+---
+
+## 8) Quick acceptance test (you can run in any runtime)
+Try these prompts and verify RAG is working:
+
+1) “Give me 8 hook angles + why each is replayable.”  
+2) “Design a 30s TikTok loop concept. 1 prop, 1 angle.”  
+3) “Transform this concept into cumbia and then into alt-rock.”  
+4) “Audit this chorus for viral signals and give minimal fixes.”
+
+If outputs reference your dataset concepts consistently, you’re done.
+
+---
+
+## 9) Common failure modes (and fixes)
+- **Generic output** → increase retrieval K; tighten prompt to require citing retrieved patterns
+- **Hallucinated claims** → enforce: “If not in retrieved context, say unknown”
+- **Too long** → cap variants; default to compact bullet outputs
+- **Bad retrieval** → improve row-to-document summaries; add better metadata filters