Dyalwayshappy/Spice

Spice is a decision runtime for agentic systems.

As execution agents become more capable, the bottleneck is shifting from:

What can agents do?

To:

What should agents do next — and why?

Spice explores this missing layer: source-backed reasoning before action, explicit trade-offs before commitment, and approval-gated handoff before execution.

✨ What’s Included

• 🧠 Decision runtime
  A structured loop for perception → state → simulation → decision → optional approval → execution → reflection.

• 💬 Interactive decision shell
  Run spice setup and spice shell to use Spice locally as a conversational decision runtime.

• 🧭 Decision Card
  Turns messy context into structured options, scores, why/why-not, risks, expected outcomes, and audit metadata.

• 🔎 Source-backed perception
  Read-only workspace perception, URL perception, external signal polling, delegated investigation artifacts, and /sources audit support.

• ✅ Approval-gated execution
  Spice does not directly execute by default. Executable actions cross an explicit approval boundary before handoff.

• 🔌 SDEP v0.1
  A protocol boundary for connecting Spice decisions to external execution agents through execute.request / execute.response.

• 🧩 Executor integrations and wrappers
  Support for dry-run, Codex, Claude Code, Hermes, SDEP-compatible executors, and wrapper-based integrations.

• 📝 decision.md guidance
  Local, user-editable decision guidance for preferences, trade-offs, and supported constraints.

🚀 Quick Start

pip install spice-runtime
spice setup
spice shell

Use shell commands such as:

/details   expand the Decision Card
/sources   inspect evidence used
/why       explain why the selected option won
/json      inspect raw artifacts
/act       move a decision toward approval-gated execution

---

## 🚧 Notes

This is still an early release. The current focus is making Spice a practical evidence-aware decision layer above agents.
We are actively improving:

- model compatibility across LLM providers
- deeper read-only repo and URL perception
- delegated read-only investigation
- executor handoff through Codex, Claude Code, Hermes, and SDEP
- decision evolution through outcomes, follow-ups, and memory
- observability and replay of decisions, approvals, sources, and outcomes

---

## 🌱 Vision

Execution agents are becoming faster, cheaper, and more capable.
But before execution, there is still a harder question:

> What should be done next, and why?

Spice is our attempt to build that layer: a decision runtime above agents.
Not another chat agent.
Not another execution framework.
A decision-first runtime before execution.
Everyone should have a Spice.

---

If you find this interesting, feel free to ⭐ the repo.