Echo-Community-Toolkit-Monorepo

Echo Community Toolkit Monorepo

Unified living workspace for VesselOS, Echo Community Toolkit, narrative engines, agents, and supporting scripts. This README orients you across the modules, agents, and custom commands that now reside in one repository. It also doubles as an operator manual for Codex/CLI agents or other LLM assistants—follow the scripted steps below to stand up the environment without guesswork.

Bring-Up Guide (for humans & LLM agents)

  1. Clone the repository (SSH deploy-key friendly) 
    git clone git@github.com:Society-for-AI-Collab-Studies-SACS/Echo-Community-Toolkit-Monorepo.git
cd Echo-Community-Toolkit-Monorepo
    • If running inside Codex CLI: ensure the deploy key is available and listed in ~/.ssh/config (see README.md history for example host alias echo-community-toolkit).
  2. Record context (recommended for automation) 
    git status --short
git remote -v

    Save outputs so the agent can restore context between sessions.

  3. Bootstrap Python & Node prerequisites 
    ./scripts/deploy.sh --full              # creates venv, installs pip deps, regenerates protobuf stubs
npm --version || echo "Node not on PATH; install Node>=20 for toolkit scripts"
    • scripts/deploy.sh is menu-driven when invoked without flags—inspect scripts/deploy.sh to tailor the bootstrap flow (e.g. skip firmware, rerun proto generation).
  4. Install per-module dependencies (batch) 
    # Toolkit
(cd Echo-Community-Toolkit && npm ci && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt)
# Audio-Visual authoring suite
(cd audio-visual-script-repo && npm ci --workspaces && python3 -m pip install -r python/requirements.txt)
# Kira Prime
(cd kira-prime && pip install -r requirements.txt && git submodule update --init --recursive)
# Garden Chronicles
(cd The-Living-Garden-Chronicles && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt Pillow)
# Dev Research Kit
(cd vesselos-dev-research && ./scripts/bootstrap.sh)

    Codex agents can execute sequentially; each command block is idempotent.

  5. Optional: Pull submodules and mirrors 
    git submodule update --init --recursive || true

    Not all directories retain submodules (many are now inlined), but this keeps legacy references aligned.

  6. Verify environment 
    python3 -m pytest -q                 # top-level tests/
(cd Echo-Community-Toolkit && node verify-integration.js || true)
(cd kira-prime && python3 vesselos.py validate || true)

    Allow failures when optional tooling (Node, Pillow, etc.) is absent; the README modules explain how to resolve them.

  7. Document state 
    git status --short

    A Codex agent should output summaries back to the operator and stop if unexpected diffs appear.

Link index for automation:

Repository Constellation

Full ASCII trees and subsystem context live in architecture.md.

Monorepo Root
├─ audio-visual-script-repo/      Audio-visual authoring UI + engine (Node/Python)
├─ Echo-Community-Toolkit/        Core hyperfollow + soulcode toolkit (Node/Python)
├─ echo_soulcode/                 Vendored Python package backing soulcode tests/tools
├─ The-Living-Garden-Chronicles/  Narrative generation + stego validator
├─ The-Living-Library/            Collab scaffolding + dictation experiments
├─ kira-prime/                    Unified CLI, agents, and collab server
├─ vessel-narrative-mrp/          Minimal narrative payload generator
├─ vesselos-dev-research/         Research-grade VesselOS CLI & docs
├─ agents/                        Standalone gRPC agents (garden, limnus, kira…)
├─ docker/                        Dockerfiles and compose stacks
├─ protos/                        gRPC/Protobuf interface contracts
├─ scripts/                       Deployment and automation helpers
├─ shared/                        Cross-project Python utilities
├─ sigprint/                      EEG signature codec + tests
├─ tests/                         Cross-repo integration tests
└─ pr/                            Scratch space for release and verification runs

Agent Signal Flow

SIGPRINT Streams
    │
    ▼
 Garden Agent ──▶ Echo Toolkit ──▶ Limnus Ledger ──▶ Kira Prime ──▶ Deploy / Publish
    │                                   │
    └──────────────▶ Narrative Engines ─┘

Phase Roadmap (0–6)

LLM operators can progress through the implementation roadmap one phase at a time. Each guide captures objectives, deliverables, and test hooks so automation stays aligned with human context.

Each phase guide lists the commands to run, fixtures to prepare, and criteria for declaring the phase complete. Treat them as living specs—update the docs when new insights land.

Continuous Integration

The consolidated workflow at .github/workflows/ci.yml now drives six parallel checks on every push:

Mirror the CI locally before opening a PR:

# Root smoke + stego suites
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python -m pytest -q

# Module-specific runners
./scripts/ci/run_toolkit_ci.sh
./scripts/ci/run_kira_ci.sh
./scripts/ci/run_chronicles_ci.sh
./scripts/ci/run_research_ci.sh

Remember to refresh the shared deps when editing parity logic or codecs:

.venv/bin/pip install -r requirements.txt
python -m grpc_tools.protoc -Iprotos --python_out=protos --grpc_python_out=protos protos/agents.proto

Module Playbook

Echo-Community-Toolkit (Echo-Community-Toolkit/)

Audio-Visual Script Suite (audio-visual-script-repo/)

The-Living-Garden-Chronicles (The-Living-Garden-Chronicles/)

The-Living-Library (The-Living-Library/)

Kira Prime (kira-prime/)

Vessel Narrative MRP (vessel-narrative-mrp/)

VesselOS Dev Research (vesselos-dev-research/)

Shared Tooling

Agents

Agent Path How to run Description
Garden Narrative agents/garden/narrative_agent.py python agents/garden/narrative_agent.py --config config.yaml Transforms SIGPRINT triggers into narrative summaries over gRPC (port 50052 by default).
Kira Validation agents/kira/kira_agent.py python agents/kira/kira_agent.py --help Performs ritual validation, publishes reports, and coordinates Kira actions.
Limnus Ledger agents/limnus/ledger_agent.py python agents/limnus/ledger_agent.py --workspace ./state Manages ledger memory, stego payloads, and semantic recall.
Journal Bridge agents/journal/journal_agent.py python agents/journal/journal_agent.py --input transcripts/ Turns human input streams into structured events for the pipeline.
SIGPRINT Bridge agents/sigprint_bridge/bridge_agent.py python agents/sigprint_bridge/bridge_agent.py --stream data/eeg.npy Couples raw EEG epochs to SIGPRINT encoders and forwards signatures.
Mock Agents agents/mocks/ python agents/mocks/garden_stub.py (example) Lightweight stubs for local integration tests and CI smoke runs.

Each agent exposes --help for additional flags (ports, workspace paths, theme overrides, etc.). gRPC interfaces map to messages in protos/agents.proto.

Custom Commands & Scripts

Tip: all scripts support --help or inline usage comments; inspect them before running against production data.

CI Status & Quicklinks

Badges – Each workflow surfaces the latest main branch health. The aggregate ci.yml job fans out across Node and Python suites (audio-visual workspaces, Toolkit, Kira Prime, Garden Chronicles, Research kit, and root smoke tests); module-specific workflows stay available for targeted reruns.

Actions quicklinks – Shortcut filters for the repository Actions tab:

Module Actions Dashboard
Monorepo aggregate https://github.com/Society-for-AI-Collab-Studies-SACS/Echo-Community-Toolkit-Monorepo/actions?query=workflow%3A%22Monorepo+CI%22
Echo-Community-Toolkit Monorepo https://github.com/Society-for-AI-Collab-Studies-SACS/Echo-Community-Toolkit-Monorepo/actions
Kira Prime CLI https://github.com/Society-for-AI-Collab-Studies-SACS/Echo-Community-Toolkit-Monorepo/actions?query=workflow%3AKira
The Living Garden Chronicles https://github.com/Society-for-AI-Collab-Studies-SACS/Echo-Community-Toolkit-Monorepo/actions?query=workflow%3AGarden
VesselOS Dev Research https://github.com/Society-for-AI-Collab-Studies-SACS/Echo-Community-Toolkit-Monorepo/actions/workflows/ci.yml?query=workflow%3A%22Monorepo+CI%22+job%3Avesselos-research

Use the pre-applied filters to reach module-specific workflow history quickly. Keep every module green before coordinating cross-stack releases.

The full roadmap for enhancing module workflows, environment hygiene, and test coverage lives in docs/integration-enhancement-plan.md.

See docs/echo-harmonizer.md for the complete Echo Harmonizer integration validator specification, docs/echo-harmonizer.yaml for the structured rails metadata, and docs/echo-harmonizer-rails-compliance.md for a Rails compliance summary.

Configuration Reference

Environment variables keep secrets and deployment toggles out of source control. Copy .env.sample to .env (or .env.integration, .env.production, etc.) and define values locally, then source the file or let your process manager pick it up. Never commit concrete .env files—use CI secrets for shared automation.

Agent Environment Variables

Agent Variable Purpose
Garden (agents/garden/narrative_agent.py) – No overrides required; relies on workspace-local state.
Echo (agents/echo/echo_agent.py) – No overrides required.
Limnus (agents/limnus/ledger_agent.py) KIRA_VECTOR_BACKEND Selects the semantic backend (e.g. faiss, defaults to in-memory).
  KIRA_VECTOR_MODEL Overrides the embedding model used for vectors.
  KIRA_SBERT_MODEL Legacy alias for the SentenceTransformer model (default all-MiniLM-L6-v2).
  KIRA_FAISS_INDEX Filesystem path for the FAISS index when that backend is active.
  KIRA_FAISS_META Filesystem path for FAISS metadata (IDs, dimensions).
Kira (agents/kira/kira_agent.py) GH_TOKEN / GITHUB_TOKEN GitHub token for release/publish flows executed via gh.
Journal (agents/journal/journal_agent.py)* – No environment configuration required today.
Sigprint Bridge (agents/sigprint_bridge/bridge_agent.py)* – No environment configuration required today.

* Planned/auxiliary agents operating only on local state and CLI flags.

All agents read/write under workspaces/<id>/state/. Follow the same UPPER_SNAKE_CASE convention when adding new toggles.

Script & Service Environment Variables

Script / Service Variable Purpose & Default
Bootstrap (scripts/bootstrap.sh) PYTHON_VERSION Python version used when creating the virtualenv (default 3.10).
  NODE_VERSION Node.js version required for toolkit automation (default 20).
Deploy (scripts/deploy_to_production.sh)* ENVIRONMENT (arg) Deployment target name (for example “production”). Defaults to production when omitted and labels the systemd service runtime.
  (others: internal) Internal variables such as WORKSPACE_ROOT and SERVICE_USER are defined inside the script.
Collab Server (kira-prime/collab-server/src/server.ts) PORT HTTP/WebSocket port (default 8000).
  COLLAB_REDIS_URL Redis connection URL (default redis://localhost:6379/0).
  COLLAB_POSTGRES_DSN Postgres DSN (default postgresql://vesselos:password@localhost:5432/vesselos_collab).
CI toggles COLLAB_SMOKE_ENABLED When set to 1, runs Dockerized collab smoke tests in CI.

* Part of the Kira Prime deployment scripts; adapt if using a simplified flow.

Testing Matrix

CI validates the stack across several layers:

Reproduce locally by running unit suites, invoking scripts/integration_complete.py, and optionally bringing up the Docker stack for smoke tests before opening a PR.

README Improvement Backlog

Appendix: Legacy Monorepo Generator

The historical VesselOS subtree generator remains available under vesselos_unified_monorepo/.

  1. Enter the generator: 
    cd vesselos_unified_monorepo
  2. Offline scaffold (no network): 
    ./scripts/vesselos_monorepo_consolidation.sh --offline --force

    Creates vesselos_unified_monorepo/vesselos-monorepo/ with agents, firmware, shared libs, docker stack, and monorepo CI.

  3. Verify: 
    cd vesselos-monorepo
./scripts/verify_integration_enhanced.sh --tests
  4. History-preserving imports: 
    GITHUB_ORG=your-org ./scripts/vesselos_monorepo_consolidation.sh --force
  5. Dry-run helper (no tree mutations): 
    ./scripts/run_local_setup_and_verify.sh --tests