LinkedIn SSI Booster

Quick Start & Setup

• Setup guide — environment, dependencies, persona graph, and calendar setup
• Usage guide — scheduling, curation, console mode, channels, and CLI examples
• CLI reference — complete command-line flag reference for schedule, curate, console, and reporting modes

Deployment & Configuration

• Docker deployment — Docker Compose profiles, GPU passthrough, services overview, and production deployment
• Environment variables — comprehensive reference for all configuration options (Buffer, Ollama, truth gate, Model2Vec, voice, image gen, database)

🐳 Docker Compose (Recommended)

Run the full stack with a single command — Ollama LLM server + Wyoming Piper TTS + SSI Booster app. The stack uses Docker Profiles (core vs full) to manage hardware resources.

Quick Start:

```bash

⚡ Quickstart (local Python)

```bash python -m venv .venv source .venv/bin/activate pip install -r requirements.txt python -m spacy download en_core_web_md cp .env.example .env cp data/avatar/persona_graph.example.json data/avatar/persona_graph.json cp data/avatar/domain_knowledge.example.json data/avatar/domain_knowledge.json cp data/avatar/narrative_memory.example.json data/avatar/narrative_memory.json

Optional extra packs: auto-discovered and merged when named domain_knowledge_*.json

cp data/avatar/domain_knowledge_java.json data/avatar/domain_knowledge_java.json cp data/avatar/domain_knowledge_python.json data/avatar/domain_knowledge_python.json cp content_calendar.example.py content_calendar.py python main.py --schedule --week 1 --dry-run

⚙️ Environment Variables

Copy .env.example to .env and fill in required values. Key variables include:

• BUFFER_API_KEY — Buffer API access
• OLLAMA_MODEL / OLLAMA_MODEL_FALLBACK — LLM models (e.g., gemma4:e4b, qwen3.5:9b)
• TRUTH_GATE_BM25_THRESHOLD — Evidence scoring threshold
• MODEL2VEC_ENABLED — Static embedding classification
• CONSOLE_USE_VOICE — Wyoming Piper TTS
• DATABASE_ENABLED — PostgreSQL dual-write mode

See docs/environment-variables.md for comprehensive reference covering 40+ configuration options across Buffer, Ollama, truth gate, Model2Vec, voice/TTS, image generation, Strudel music, and database integration.

MIT License — see LICENSE for details.

CLI Generation

Generate music directly from command line:

```bash

Knowledge-to-Music Pipeline

• Theme Extraction: Analyzes extracted knowledge base to identify recurring technical themes ranked by frequency and recency
• Technical Metaphors: Translates technical concepts into musical structures (e.g., async programming → interleaved rhythms, neural networks → layered synthesis)
• Evidence Tracking: Every lyric and pattern is grounded in extracted knowledge with full evidence ID tracing
• DoT Validation: Lyrics undergo Derivative of Truth validation to ensure factual accuracy in technical claims

Console Integration

Access Rei Toei directly in console mode:

python main.py --console

Sam> /rei-toei
Rei> ⚡ Online. I transform your technical knowledge into algorithmic music.
     What concept should we sonify today?

Sam> Generate a song about the recent ML architecture article
Rei> [Generates song concept, lyrics, and Suno prompt]

Sam> Create a Strudel pattern for that concurrent processing theme
Rei> [Generates and executes Tidal Cycles code via MCP agent]

Commands: /rei-toei or /rei to switch to Rei's personality, then describe what you want to generate.

🔍 Learning, Grounding, and Explainability Pipeline

How the system learns and adapts:

• Candidate logging: Every generated post and curated article candidate is logged, including source, topic, and all relevant metadata. This creates a full audit trail of what the system considered, not just what was published.
• Reconciliation & learning: When you publish or reject posts (via Buffer or moderation), the system reconciles what actually went live. It updates acceptance rates (priors) for each source, topic, and SSI component, so future curation floats the best-performing sources and topics to the top.
• Ranking: Article and post candidates are ranked using a combination of acceptance priors and BM25 retrieval scores, so the system learns your preferences over time and adapts what it suggests.
• Signal flow — truth gate → confidence → selection learning: Truth gate removal rates and reason codes feed directly into the confidence scorer. The confidence score routes each post to post (scheduled directly), idea (Buffer Ideas for manual review), or block. Those publication outcomes are later reconciled against Buffer — posts that actually go live raise the acceptance prior for their source, topic, and SSI component; posts that stay as ideas or get blocked do not count. Over time, sources that reliably produce clean, well-grounded posts float to the top of article ranking, while sources that consistently trigger heavy truth-gate filtering sink. The truth gate doesn't pre-filter articles — it filters the generated output — but its signal is what teaches the selection layer which articles are worth fetching next run.

How deterministic grounding and the truth gate work:

• Fact retrieval: For every post or answer, the system retrieves relevant facts from your persona graph (projects, skills, outcomes) using BM25Okapi — a production-grade IR algorithm. This ensures rare, high-signal skills and projects are prioritized.
• Prompt balance rules: Prompts require every factual claim to be grounded in either the article or your persona facts. Personal references are capped, and invented stats/dates/companies are forbidden.
• Truth gate: After generation, a four-layer deterministic filter removes any sentence with unsupported numbers, dates, company names, or project-tech mismatches unless the claim is found in evidence. The layers are: BM25 evidence scoring → per-sentence Derivative of Truth gradient (4-term formula with token overlap) → spaCy semantic similarity floor for specific-claim sentences → spaCy NER org-name validation. ORG validation includes hardening against common technical false positives (for example S3, AI Q&A, Java 21) and is backed by an expanded evidence set from auto-merged domain_knowledge_*.json files. Each removed sentence is logged with a reason code (weak_evidence_bm25, weak_dot_gradient, low_semantic_similarity, unsupported_org, etc.) that feeds the confidence scoring pipeline.

---

Database Integration (PostgreSQL)

The system now supports dual-write mode with PostgreSQL for improved data integrity, query performance, and concurrent access. Database integration is optional — the system continues to work with file-based storage (JSON/JSONL) by default.

Setup (Docker):

1. Add to .env:

   DATABASE_ENABLED=true
   POSTGRES_USER=ssi_booster
   POSTGRES_PASSWORD=your_secure_password_here
   POSTGRES_DB=linkedin_ssi_booster
   DATABASE_URL=postgresql://ssi_booster:your_password@postgres:5432/linkedin_ssi_booster
   

1. Start PostgreSQL container:

   docker compose --profile core up -d postgres
   

1. Verify tables created:

   docker exec -it ssi_booster_postgres psql -U ssi_booster -d linkedin_ssi_booster -c "\dt"
   

Database Schema:

The system stores 17 tables across 5 domains:

• Avatar Intelligence: persona_graph, projects, companies, skills, claims, domains, domain_facts, domain_relationships, extracted_facts, narrative_memory
• Selection Learning: candidate_records, published_records
• Truth Gate Learning: moderation_events, confidence_decisions
• Derivative of Truth: truth_trajectories, truth_trajectory_points
• Migrations: schema_migrations

Migration from JSON/JSONL:

```bash