Skip to content

quickstart.md

Latest commit

 

History

History
130 lines (100 loc) · 4.03 KB

quickstart.md

File metadata and controls

130 lines (100 loc) · 4.03 KB
Raw

Quickstart Guide

Get Synapse_COR running in under 5 minutes.

Prerequisites

  • Python 3.9+ (check: python3 --version)
  • At least one LLM source — see options below
  • requests library is optional (pip install requests only needed for some adapters)

No LLM yet? See BOOTSTRAP_GUIDE.md for step-by-step setup. The fastest path: npm install -g @google/gemini-cli — free Gemini access, no account needed.

Install

git clone https://github.com/FutronPrime/synapse-cor
cd synapse-cor
bash install.sh

The installer:

  1. Checks for Python 3.9+ (required)
  2. Scans for available LLM providers (Ollama, Gemini CLI, API keys)
  3. Installs synapse-forge binary to ~/.synapse-forge/bin/
  4. Prompts you to add the bin directory to PATH

New to all of this? Start with BOOTSTRAP_GUIDE.md instead. It covers installing Python, Node.js, and a free LLM from a completely clean system.

Add to PATH (put in ~/.bashrc or ~/.zshrc):

export PATH="$HOME/.synapse-forge/bin:$PATH"

Point at Your LLM

Ollama (local, recommended):

export SYNAPSE_FORGE_URL=http://localhost:11434/v1
export SYNAPSE_FORGE_MODEL=llama3.2
# No API key needed

OpenAI:

export SYNAPSE_FORGE_URL=https://api.openai.com
export SYNAPSE_FORGE_API_KEY=sk-...
export SYNAPSE_FORGE_MODEL=gpt-4o-mini
export SYNAPSE_FORGE_FALLBACK=gpt-3.5-turbo

Free cloud (OpenRouter):

export SYNAPSE_FORGE_URL=https://openrouter.ai/api/v1
export SYNAPSE_FORGE_API_KEY=sk-or-...
export SYNAPSE_FORGE_MODEL=meta-llama/llama-3.2-1b-instruct:free

Verify

synapse-forge status

Expected output:

Synapse_COR Engine v3 — status
Forge endpoint: http://localhost:11434/v1 [REACHABLE]
Specialists: 6 registered
Cascade fallback: configured

First Run

# Fast-path (single dispatch):
synapse-forge run "explain what the largest file in the current directory is and why it matters"

# Full pipeline:
synapse-forge plan "audit my Python codebase for security issues"
# → writes PLAN_<timestamp>.json

synapse-forge compose PLAN_<timestamp>.json
# → registers security-auditor specialist

synapse-forge dispatch PLAN_<timestamp>.json
# → runs deterministic scans, fires specialist, validates output

Common Commands

synapse-forge plan "<goal>"          # Analyze goal → PLAN.json
synapse-forge compose <plan.json>    # Register specialists from plan
synapse-forge dispatch <plan.json>   # Execute full pipeline
synapse-forge run "<goal>"           # Fast-path: plan+compose+dispatch in one
synapse-forge status                 # Show endpoint health + registered specialists
synapse-forge cor-template           # Print blank CoR template
synapse-forge persona <name>         # Show specialist persona for <name>
synapse-forge memory search "<q>"    # Search specialist memory

Your First Specialist

# Create a custom specialist on the fly:
synapse-forge run "act as a data analyst: find the top 5 largest directories in /var/log and explain what they contain"

Synapse_COR will:

  1. Detect this needs find + du (deterministic) + analysis (probabilistic)
  2. Run du -sh /var/log/* | sort -rh | head -5 with zero tokens
  3. Fire a data-analyst specialist with the real data as grounding context
  4. Return a grounded, non-hallucinated analysis

Troubleshooting

Problem Fix
command not found: synapse-forge Add ~/.synapse-forge/bin to PATH
Connection refused at Forge endpoint Start Ollama: ollama serve
No module named requests pip install requests
Specialist not found Run synapse-forge status to see what's registered
Slow responses Use a smaller/quantized local model

Next Steps

  • Read docs/architecture.md to understand the full pipeline
  • See examples/ for worked walkthroughs (security-auditor, file-archaeologist, content-strategist)
  • Read docs/extending.md to add your own specialists
  • Check adapters/ for your specific environment (Claude Code, Codex, Gemini, OpenSwarm)