Agents can execute.
But they don’t know what to do next.
Spice is a decision-layer runtime — a brain above agents. inspired by the rise of execution agents like OpenClaw and the idea of world model.
While execution agents (Claude Code, OpenClaw, Codex) are getting better at doing things,
Spice focuses on the missing layer:
👉 What should be done next — and why.
To gain a more intuitive understanding of Spice,
please visit our carefully prepared demo about conflicts between life and work events: Spice-live-demo
- Bilibili
Click the image to watch the full demo video of using Spice to handle conflicts between the digital and physical worlds.
- YouTube
Click the image to watch the full demo video of using Spice to handle conflicts between the digital and physical worlds.
Today, we have powerful agents that can do almost anything:
- write code
- analyze data
- automate workflows
But when you sit down to use them, you still face the same problem:
What should I do next?
That’s the hard part.
The real bottleneck is:
Decision-making.
Spice is designed to solve that.
Spice provides a structured cognitive loop inspired by the concept of world model :
perception → state model → simulation → decision → execution → reflection
It allows AI systems to:
- understand context (state)
- reason about possible futures (simulation)
- make structured decisions (decision)
- delegate actions to agents (execution)
- learn from outcomes (Decision Evolution)
"I want to quickly build a lightweight tool for a small group of friends."
A simple, real-world goal with clear constraints
starts from intent
From options → structured decision space
Decision becomes action
Spice focuses on the decision layer.
In a full workflow, the selected decision can be passed to external agents (e.g. codex and claude code) for execution.
This example stops at decision + next step.
➡️ Next, we will take this exact scenario and connect it to an external agent to actually build the tool end-to-end.
Decision → Execution → Outcome → Reflection
This is the full loop Spice is designed to enable.
The underlying model is domain-agnostic.
Spice is a general decision runtime that can be applied to any domain where:
- there is context (state)
- there are possible futures (simulation)
- decisions need to be made
- actions can be executed by agents
This includes:
- individual decision making
- product and business strategy
- software development workflows
- operations and automation systems
Spice is not limited to one use case.
It is a foundation for building decision systems.
The main user-facing interface in Spice is decision.md.
Users configure how Spice should compare candidate decisions by editing:
.spice/decision/decision.md
This file is decision guidance. It is not memory, not a prompt dump, not an execution runbook, and not an agent workflow.
Runtime-active in v1:
- Primary Objective — the dominant optimization direction
- Preferences / Weights — score dimensions used during candidate comparison
- Hard Constraints — veto boundaries, when supported by the active policy/domain adapter
- Trade-off Rules — a constrained executable subset for resolving conflicts
Runtime-inactive in v1:
- Decision Principles
- Evaluation Criteria
- Reflection Guidance
The bundled default profile is a starter template. Users should edit their local decision.md; they should not edit support JSON as normal configuration.
Runtime support comes from the active policy or domain adapter. The copied support JSON is only for explain/demo/debug flows.
See docs/decision.md and docs/decision_quickstart.md for the support contract and quickstart.
Install from source (latest features, for development)
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 .Install from PyPI (stable, recommended)
pip install spice-runtimepip install -U spice-runtime
spice --helpThe fastest way to experience Spice is the integrated quickstart:
spice quickstart --forceThis starts from the bundled example domain and walks through the full Spice boundary:
decision.md -> example domain runtime -> OpenRouter/local LLM -> optional SDEP execution boundary
It creates:
.spice/quickstart/ # deterministic core-loop example
.spice/quickstart_llm/ # LLM-ready example runtime
.spice/decision/decision.md # user-editable decision profile
.spice/decision/support/default_support.json
The generated example runs immediately with deterministic defaults. No API key is required for the first run.
perception -> state -> decision -> execution -> reflection
The default quickstart proves that Spice can:
- load a decision profile
- validate and explain decision guidance
- run a domain-specific decision loop
- attach model advisory through an explicit provider
- keep execution external, pluggable, and auditable through SDEP
The bundled quickstart domain is an example. Real projects define their own DomainSpec, domain adapter, supported score dimensions, constraint checks, and SDEP execution boundary.
If you only want to see the deterministic Spice core loop:
spice quickstart --core-only --forceThis creates only:
.spice/quickstart/
Use this when you want to inspect the smallest loop without LLM wiring or decision.md setup.
The main user-editable file is:
.spice/decision/decision.md
The safest first customization is the scoring weights:
Preferences:
- outcome_value: 0.40
- risk_reduction: 0.25
- reversibility: 0.20
- confidence_alignment: 0.15For example, to prefer safer and more reversible decisions:
Preferences:
- outcome_value: 0.25
- risk_reduction: 0.35
- reversibility: 0.25
- confidence_alignment: 0.15decision.md configures decision selection. It is not memory, an agent prompt, or an execution script.
spice decision explain .spice/decision/decision.md --support-json .spice/decision/support/default_support.jsonUse --json for structured output.
The explanation shows:
- loaded artifact id/version
- validation status
- runtime-active and runtime-inactive sections
- supported and unsupported score dimensions
- supported and unsupported hard constraints
- supported and unsupported trade-off rules
Runtime support comes from the active policy or domain adapter. Editing support JSON alone does not add runtime capability.
Attach a hosted model to the generated example runtime:
export OPENROUTER_API_KEY="your-openrouter-api-key"
export SPICE_DOMAIN_MODEL="openrouter:anthropic/claude-3.5-sonnet"
python .spice/quickstart_llm/run_demo.pyOptional OpenRouter attribution headers:
export SPICE_OPENROUTER_SITE_URL="https://github.com/Dyalwayshappy/Spice"
export SPICE_OPENROUTER_APP_NAME="Spice"SPICE_DOMAIN_MODEL="ollama run qwen2.5" python .spice/quickstart_llm/run_demo.pyModel selection is explicit:
deterministicuses the built-in deterministic provideropenrouter:<model-id>uses the OpenRouter provider- any other value is treated as a subprocess command
Any subprocess command must read a prompt from stdin and return structured model output. Spice does not auto-load hidden model configuration in v1.
The quickstart shows the file-based configuration flow. In application code, attach the profile explicitly:
from spice.decision import guided_policy_from_profile
policy = guided_policy_from_profile(
base_policy,
".spice/decision/decision.md",
)The active policy/domain adapter remains the source of runtime capability.
Models help Spice reason, simulate, and advise. External agents execute when you choose to connect them.
Decision -> ExecutionIntent -> external agent -> ExecutionResult -> Outcome -> Reflection
Run the included SDEP execution demo:
python examples/sdep_agent_demo/run_sdep_adapter_demo.pyFor production integrations, SDEP is the execution boundary:
- Spice produces a structured execution intent
- external agents execute through SDEP
- execution results return as structured outcomes
- Spice absorbs decision-relevant outcomes without owning execution internals
Mock and direct command executors are local test/debug utilities. They are not the recommended public execution path.
Execution is optional and pluggable, but when Spice talks to external agents, SDEP is the canonical boundary. It is not mixed into decision.md.
1. clone and install Spice
2. run spice quickstart
3. edit .spice/decision/decision.md
4. validate with spice decision explain
5. choose OpenRouter, deterministic, or local subprocess model
6. run the example domain
7. replace the example domain with your own DomainSpec/domain adapter
8. optionally connect external execution agents through SDEP
Spice includes a working reference integration with Hermes to demonstrate the full decision-to-execution loop.
WhatsApp / GitHub signal
-> Spice-Hermes Bridge
-> Spice decision_hub_demo
-> WorldState / ActiveDecisionContext
-> structured simulation
-> decision.md guided selection
-> SDEP execute.request
-> Hermes/Codex execution
-> SDEP execute.response
-> execution_result_observed
-> Spice state update
This integration demonstrates the intended separation:
- Spice handles state, simulation, decision selection, and decision evolution
- Hermes handles messaging ingress and execution
- SDEP is the execution boundary between decision and execution
- Bridge converts external signals and execution outcomes into structured Spice observations
This is a reference integration, not Spice core.
Start here:
spice-hermes-bridge/README.md— run the local WhatsApp + Hermes + Spice loopexamples/decision_hub_demo/— simulation-driven decision demo domainexamples/sdep_quickstart/— build an SDEP executorschemas/sdep/v0.1/— SDEP JSON Schemasexamples/sdep_payloads/v0.1/— SDEP example payloads
Use this section to understand how Spice sits above execution agents without becoming an execution framework.
Spice transforms your world into a structured decision system.
It enables a new way to think, decide, and act:
-
Perception
Understand your world and extract meaningful signals -
State Modeling
Turn it into a structured decision model -
Simulation
Explore possible futures before taking action -
Decision
Compare trade-offs and then give you decision-making assistance. -
Execution (optional)
Delegate actions to external agents (e.g. Claude Code, Codex) -
Reflection
Learn from outcomes and continuously improve decisions
SDEP is a protocol-layer specification for connecting a decision system with external execution agents.
It defines a standardized boundary between:
-
Decision (what to do)
-
Execution (how it is done)
If you want to understand or implement SDEP, start from:
- Protocol spec:
docs/sdep_v0_1.md - JSON Schemas:
schemas/sdep/v0.1/ - Example payloads:
examples/sdep_payloads/v0.1/ - Executor quickstart:
examples/sdep_quickstart/ - Wrapper template:
examples/sdep_wrapper_template/
SDEP v0.1 defines:
execute.requestexecute.responseagent.describe.requestagent.describe.response
The schemas validate the public wire contract. Domain-specific payloads such as execution.parameters, execution.input, metadata, and traceability remain open extension objects.
Modern agent systems often follow patterns like ReAct or reinforcement learning loops, where:
reasoning and acting are interleaved inside a single loop
execution is implicit, embedded in the agent runtime
SDEP takes a different approach:
It externalizes the “Act” step into a first-class protocol boundary
| Layer | Role |
|---|---|
| Methodology (ReAct, RL) | how agents think & learn |
| Protocol (SDEP) | how decisions cross into execution |
| Execution | how actions are actually performed |
In most systems today:
-
decision logic is tightly coupled to specific tools
-
execution is not standardized
-
results lack the determinism and transparency required for production-grade reliability
SDEP introduces a clean separation:
- Decision layer (Spice) → produces structured intent
- Execution layer (agents/tools) → performs actions
This enables:
- interchangeable execution backends
- explicit decision → action mapping
- full traceability of “why this action happened”
SDEP is not a reasoning framework.
It is the interface contract between thinking and doing.
SDEP defines a minimal set of protocol primitives:
A structured representation of what should be executed.
Includes:
- intent type
- target (tool / agent / environment)
- input payload
- optional constraints / metadata
A normalized representation of what actually happened.
Includes:
- status (success / failure / partial)
- outputs (logs, artifacts, messages)
- signals (e.g. requires_attention, retryable)
A domain-aware interpretation of execution results:
- maps raw results → state updates
- enables reflection and learning
SDEP formalizes the boundary between decision and execution:
Decision
↓
ExecutionIntent
↓
[ SDEP Boundary ]
↓
External Agent / Tool
↓
ExecutionResult
↓
Outcome
↓
Reflection / State Update
Key idea:
Everything crossing the boundary is structured, explicit, and observable
- ReAct: reasoning + acting inside one loop
- SDEP: extracts “Act” into a protocol
- RL: optimizes behavior via reward signals
- SDEP: defines how actions are executed and observed
Tool calling is usually:
- implicit
- model-specific
- hard-coded
SDEP makes it:
- explicit
- model-agnostic
- auditable
- replayable
-
Same Brain, Different Agent Switch execution backends without changing decision logic
-
Auditable systems Every action has a traceable intent and result
-
Replay & simulation Re-run decisions against different execution environments
-
Composable execution layer CLI, APIs, agents, humans — all become interchangeable executors
Execution will become cheap and abundant. Decision will become the bottleneck.
SDEP exists to ensure:
- decision systems are not locked into execution tools
- execution remains replaceable infrastructure
- the boundary between thinking and acting is explicit and controllable
Spice supports an open wrapper ecosystem.
Even if an external agent does not natively support SDEP, it can still be integrated through a wrapper.
A wrapper is a protocol bridge between Spice and external agents.
Spice (SDEP) ↔ Wrapper ↔ External Agent
- Spice speaks in ExecutionIntent / ExecutionResult (SDEP)
- Agents speak in their own formats (CLI, JSON, HTTP, SDK, etc.)
- The wrapper translates between the two
SDEP is a newly launched protocol that connects the decision layer with external execution agents; its ecosystem still needs development.
Wrappers make Spice immediately compatible with the existing ecosystem:
- Integrate CLI agents, SDK-based tools, and remote services
- Avoid modifying existing agents
- Enable gradual adoption of SDEP
- Native SDEP agents → connect directly
- Non-SDEP agents → connect via wrapper
- Multiple agents → route by capability or context
Wrappers exist to make Spice useful today.
They allow us to integrate with existing agents without requiring changes.
But we believe this is a transitional layer.
In the long term, we expect more agents to adopt SDEP natively —
enabling a clean, direct connection between decision systems and execution.
Wrappers make Spice practical.
SDEP is where the real value compounds.
spice/
├── spice/ # 🧠 Core decision runtime framework
│ ├── core/ # Runtime loop + state store
│ ├── protocols/ # Observation/Decision/Execution contracts
│ ├── decision/ # Decision policy primitives
│ ├── domain/ # DomainPack abstractions
│ ├── domain_starter/ # New-domain scaffold templates
│ ├── executors/ # Executor interface + SDEP adapter
│ ├── llm/ # Optional LLM core/adapters/providers
│ ├── memory/ # Context/memory components
│ ├── replay/ # Replay utilities
│ ├── shadow/ # Shadow-run evaluation
│ ├── evaluation/ # Eval helpers
│ ├── entry/ # Core CLI/tooling (quickstart/init domain)
│ └── adapters/ # External system adapters
├── tests/ # ✅ Core test suite
├── docs/ # 📚 Architecture + protocol docs (incl. SDEP)
├── schemas/ # 📐 Machine-readable SDEP JSON Schemas
├── examples/ # 🧪 Runtime, decision, and SDEP examples
│ ├── decision_hub_demo/ # Simulation-driven decision demo domain
│ ├── sdep_agent_demo/ # Minimal SDEP executor demo
│ ├── sdep_quickstart/ # SDEP quickstart for executor authors
│ ├── sdep_payloads/ # Example SDEP request/response payloads
│ └── sdep_wrapper_template/ # Template for wrapping non-SDEP agents
├── spice-hermes-bridge/ # 🌉 Reference bridge: WhatsApp/GitHub -> Spice -> SDEP -> Hermes
├── pyproject.toml # 📦 spice-runtime package metadata
├── README.md # 📝 Core project overview
├── LICENSE # ⚖️ MIT
└── .gitignore # 🙈 Ignore rules
Spice is an evolving decision-layer system.
We’ve built the core runtime, personal reference app, and SDEP-based execution loop.
Next, we focus on expanding capabilities and ecosystem.
PRs are welcome — the system is designed to be modular and extensible.
- Decision runtime (perception → state → decision → reflection)
- Integrated quickstart and domain scaffolding
- SDEP (Decision → Execution protocol)
- Wrapper ecosystem for external agents
- End-to-end loop (decision → execution → outcome)
-
Richer decision modeling
Better simulation, trade-off analysis, and multi-step reasoning -
Stronger memory layer
Cleaner WorldState governance, context slicing, and decision-relevant state updates -
More execution integrations
Expand agent ecosystem (CLI, APIs, tools, services) -
Multi-step decision workflows
From single decisions → structured plans and execution chains -
Better observability
Inspect decisions, execution traces, and state transitions
-
Domain expansion
Apply Spice to new domains beyond personal (software, ops, research) -
Native SDEP ecosystem
More agents supporting SDEP directly (less reliance on wrappers) -
Persistent decision systems
Systems that continuously learn and evolve over time
We believe the future of AI is not just execution —
but better ways to think and decide.
Spice is an attempt to build a new layer in the AI stack:
a decision layer above agents.
Our goal is simple:
Everyone should have a Spice.
A system that:
- understands your world
- maintains your state
- helps you think through decisions
- and takes action when needed
Not just a tool.
Not just a chatbot.
But a decision brain
that evolves with context, outcomes, and goals over time.
We've recently been considering the commercialization path for Spice, and to achieve our vision, we'll be moving towards a General AI Brain. We're currently preparing a very compelling demo, so stay tuned!
We are still early.
But we believe this direction leads to:
- more thoughtful decisions
- more capable systems
- and a new way to interact with AI
Spice is not just an assistant.
It is a step toward a decision brain for everyone.
Finally，Thanks to everyone on LinuxDo for their support! Welcome to join https://linux.do/ for all kinds of technical exchanges, cutting-edge AI information, and AI experience sharing, all on Linuxdo!
⭐ Star us if you find Spice interesting
Everyone should have a Spice — a decision brain for thinking and action.