Skip to content

SPARK_ECOSYSTEM_LAUNCH.md

Latest commit

 

History

History
102 lines (75 loc) · 4.31 KB

SPARK_ECOSYSTEM_LAUNCH.md

File metadata and controls

102 lines (75 loc) · 4.31 KB
Raw

Spark Ecosystem Launch Guide

This is the public launch contract for the starter Spark stack installed by:

spark setup

The default bundle is telegram-starter.

Modules

Module Launch role Owns
spark-researcher Research, advisory packets, chip authoring, bounded improvement loops research runtime and memory packet workflows
spark-character Persona, voice consistency, scoring, and opt-in character evolution Spark character runtime and voice evaluation
spark-intelligence-builder Runtime core for identity, provider routing, memory bridge, and adapter logic Builder state, provider profiles, domain-chip activation
domain-chip-memory Default memory/domain chip substrate memory benchmark logic, packet discipline, chip evaluation
spawner-ui Local execution plane and mission board missions, project creation flows, multi-step execution UI
spark-telegram-bot Telegram ingress owner Telegram bot token, long polling, operator chat surface

Runtime Shape

Telegram user
  -> spark-telegram-bot
  -> spark-intelligence-builder for memory, researcher, identity, and LLM routing
  -> spark-character for persona rendering, voice scoring, and output sanitizing
  -> domain-chip-memory when Builder activates the default memory chip
  -> spark-researcher for research/advisory/chip-authoring flows
  -> spawner-ui for missions, project creation, and execution

Telegram V1 Rules

  • spark-telegram-bot is the only module that receives the Telegram bot token.
  • Telegram uses long polling for this launch.
  • Webhooks are intentionally disabled in v1.
  • TELEGRAM_RELAY_SECRET is generated by Spark CLI and shared only between Telegram and Spawner.
  • Telegram is private by default: /start and /myid are public; everything else requires admin/allowlist/public opt-in.

LLM Routing

Spark CLI can configure:

  • local Ollama
  • Z.AI GLM through the coding endpoint
  • OpenAI
  • Anthropic

Cloud API keys are stored through Spark's secret backend. Generated module env files should contain non-secret provider metadata such as provider name, model, and base URL. They should not contain raw cloud API keys unless a module explicitly declares that secret as file-backed.

What Users Can Do After Setup

After spark setup and spark start spark-telegram-bot, a configured operator can:

  • chat with Spark through Telegram
  • use Builder-backed memory/research when the Builder bridge is available
  • run /diagnose to see Telegram, LLM, Builder, memory, and mission relay state
  • run /run <goal> to create a Spawner mission
  • run local recursive Builder chip loops with /recursive start <chipKey> rounds <n>
  • inspect local recursive loops with /recursive sessions, /recursive report, and /recursive trace
  • use /board and /mission <status|pause|resume|kill> <missionId>
  • use the installed Researcher and domain-chip-memory repos for local research and memory/chip work

Public Labs Outside The Starter Bundle

Some public Spark labs are intentionally not installed by default until they expose the same installable module contract as the starter modules:

  • spark-domain-chip-labs: creator standards for domain chips, benchmark packs, specialization paths, autoloop policies, and review packets.
  • spark-personality-chip-labs: portable personality chip schemas and experiments.
  • spark-voice-comms: voice communication hooks, profiles, and provider examples.

These labs are usable for builders, but Spark CLI should not tell public users that Spark Swarm, hosted Workspace review, or network submission is required for local experiments.

Not In This Launch

  • no dashboard/resonance API
  • no required service on port 8787
  • no Telegram webhook listener
  • no public network exposure for Spawner control APIs
  • no third-party untrusted module marketplace
  • no public Spark Swarm Workspace/network-submission dependency
  • no automatic install of every public lab repo

Verification

Run:

spark status --json
spark secrets list
spark logs spark-telegram-bot

Expected:

  • telegram-starter is the configured bundle
  • spark-telegram-bot is the Telegram ingress owner
  • all starter modules are installed
  • the selected LLM provider is reflected in generated metadata
  • repair hints do not mention SPARK_API_URL, SPARK_DASHBOARD_URL, or port 8787