⚙ Install

Install from source

git clone https://github.com/Dyalwayshappy/Spice.git
cd Spice

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -U pip
pip install -e .

Then verify:

spice --help

Install from PyPI (stable, recommended)

pip install spice-runtime

Then verify the CLI:

spice --help

❗️ 30s Dogfooding example

In this demo, Spice is used to decide its own next step: improving state-as-context, strengthening read-only workspace perception, or expanding executor handoff.

The default view stays conversational, while /details expands the full auditable Decision Card.

---

🚀 Quick Start

The fastest way to try Spice is the interactive decision shell.

pip install spice-runtime
spice setup
spice shell

spice setup initializes a local Spice workspace:

.spice/
  config.json          # LLM / executor / perception config
  decision.md          # user-editable decision guidance
  state/state.json     # local decision state
  sessions/            # conversation/session records
  runs/                # run artifacts
  decisions/           # Decision Cards
  perceptions/         # workspace / URL / delegated perception artifacts
  investigations/      # read-only investigation consent and records
  approvals/           # approval checkpoints
  outcomes/            # execution outcomes
  conversations/       # shell conversation turns
  memory/              # decision memory and summaries
  cache/               # runtime cache
  executors/           # local executor metadata/config
  skills/              # local skill metadata
  .env                 # optional saved API keys, if configured during setup

Then start a session:

spice shell

Try:

spice> Read this repo and tell me what we should prioritize next.
spice> Why not option B?
spice> Give me a two-week plan for A.
spice> /execute <approval_id>

By default, Spice responds conversationally and keeps the audit card folded.

Useful shell commands:

/details     expand the full Decision Card
/sources     show evidence and sources used
/why         explain why the selected option won
/sim         show simulation metadata
/json        inspect raw artifacts
/context     inspect compiled decision context
/workspace   inspect workspace perception
/refine      adjust the latest decision
/execute     request approval-gated execution
/help        show shell commands

---

7. Legacy Quickstart And Domain Demos

The older framework quickstart is still available for people building custom domains or studying the deterministic core loop:

spice quickstart --force

Core-only mode:

spice quickstart --core-only --force

That flow creates example artifacts under:

.spice/quickstart/
.spice/quickstart_llm/
.spice/decision/decision.md
.spice/decision/support/default_support.json

Use this path if you are building a custom DomainSpec, policy adapter, or SDEP executor demo.

For the current interactive product experience, start with:

spice setup
spice shell

---

🎬 Demo of Spice

To gain a more intuitive understanding of Spice,

please visit our carefully prepared demo about conflicts between life and work events: Spice-live-demo

---

Demo Video

1. Bilibili

Click the image to watch the full demo video of using Spice to handle conflicts between the digital and physical worlds. </div>

---

1. YouTube

Click the image to watch the full demo video of using Spice to handle conflicts between the digital and physical worlds. </div>

---

1. Configure A Model

You can configure an LLM during spice setup, or later:

spice config enable-llm \
  --provider openrouter \
  --model minimax/minimax-m2.7

Spice will read the API key from the provider-specific environment variable.

Example:

export OPENROUTER_API_KEY="your-openrouter-api-key"
spice shell

Supported LLM providers:

Spice uses the LLM for candidate expansion, semantic routing, simulation metadata, response composition, and follow-up understanding. Runtime guardrails still own execution boundaries, evidence checks, and approval rules.

---

2. Configure An Executor

Execution is optional.

Spice can make decisions without executing anything. If you configure an executor, Spice still requires approval before crossing the execution boundary.

Supported executors:

Check executor status:

spice executor list
spice executor doctor

Execute only after approval:

spice approval list
spice approval approve <approval_id>
spice execute <approval_id>

Spice separates decision from execution:

Spice decides what should happen next.
Executors do the work after approval.

---

3.Configure Perception

Perception is how Spice gathers decision-relevant evidence.

Supported perception paths:

Examples:

spice perceive --provider poll --poll-url "https://example.com/status"
spice perceive --provider open_chronicle

In the shell, Spice can automatically trigger read-only workspace or URL perception when the user asks for evidence:

spice> Read this repo and tell me what is missing.
spice> Based on this URL, what should we do next? https://example.com/spec

Use /sources to inspect what Spice actually read.

---

6. Run One-Off CLI Decisions

You can also use Spice without entering the shell.

Advisory decision:

spice decide "What should we prioritize next?" --advise

One-shot run:

spice run --once "Read this repo and suggest the safest next action"

JSON artifact output:

spice run --once "What should we do next?" --json

Refine the latest decision:

spice refine "Assume we only have one developer for two weeks."

Inspect session history:

spice session list
spice session current
spice session timeline session.default

Check workspace health:

spice doctor

---

🔁 Reference Integration: Spice + Hermes

This repository includes a reference bridge showing how external signals can flow into Spice and how approved decisions can be handed off to Hermes through SDEP.

External signal -> Spice decision runtime -> SDEP -> Hermes executor -> outcome -> reflection

Start here if you want to study a full integration example:

• spice-hermes-bridge/README.md
• examples/decision_hub_demo/
• examples/sdep_quickstart/

This is a reference integration, not Spice core.

---

2. SDEP vs Existing Agent Patterns

vs ReAct

• ReAct: reasoning + acting inside one loop
• SDEP: extracts “Act” into a protocol

vs Reinforcement Learning

• RL: optimizes behavior via reward signals
• SDEP: defines how actions are executed and observed

vs Traditional Tool Calling

Tool calling is usually:

• implicit
• model-specific
• hard-coded

SDEP makes it:

• explicit
• model-agnostic
• auditable
• replayable

---