Skip to content

Commit 97bdf72

Browse files
OyaAIProdOyaAIProd
committed
updates
1 parent f7d3df1 commit 97bdf72

18 files changed

Lines changed: 665 additions & 556 deletions

‎DEMO.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Capturing demo assets
2+
3+
A GIF at the top of the README is the single biggest driver of stars/shares. Two
4+
to make — the **studio** (the money shot) and a **terminal** clip (reproducible).
5+
6+
## 1. Studio GIF (the money shot)
7+
8+
Shows the live DAG lighting up + the answer streaming.
9+
10+
```bash
11+
make dev # → http://localhost:4000 (set ANTHROPIC_API_KEY for real runs; canned otherwise)
12+
```
13+
14+
Record the browser with [Kap](https://getkap.co) (mac) or the Chrome DevTools
15+
Recorder / QuickTime, then convert to GIF:
16+
17+
- Frame the three columns; window ~1280×800.
18+
- Type a prompt (or click a suggestion), hit enter.
19+
- Capture **~8–10s**: nodes go amber→green, handles show `OPAQUE → hidden` /
20+
`TRANSPARENT`, the answer streams.
21+
- Trim to a tight loop. Save as `studio.gif`, drop it at the top of `README.md`.
22+
23+
Tip for a clean take: `ANTHROPIC_API_KEY` set → real, varied answers; unset →
24+
canned + instant (more deterministic for a loop).
25+
26+
## 2. Terminal GIF (reproducible, no recording)
27+
28+
[`demo.tape`](./demo.tape) renders `make demo` to a GIF with
29+
[VHS](https://github.com/charmbracelet/vhs) — no manual screen capture:
30+
31+
```bash
32+
brew install vhs
33+
vhs demo.tape # → demo.gif
34+
```
35+
36+
`make demo` itself (no key, deterministic) prints the plan executing — each node
37+
with its projection level, then the streamed answer, then "the PDF and web page
38+
stayed OPAQUE — the model never read them." Good for a tweet or the README.
39+
40+
## Where to put them
41+
42+
```md
43+
<p align="center"><img src="./studio.gif" width="800" alt="oya Studio"></p>
44+
```
45+
46+
Lead the README with the studio GIF; use the terminal GIF in the launch thread
47+
(see [`LAUNCH.md`](./LAUNCH.md)).

‎LAUNCH.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Launch kit
2+
3+
Copy-paste material for launching oya. Numbers are from a 3-trial `claude-opus-4-7`
4+
run (see `benchmarks/`); keep the "drop-in for Mastra" and "plan, don't react"
5+
phrasing — they're the hooks.
6+
7+
---
8+
9+
## Tweet (single)
10+
11+
> Every AI-agent framework is a token loop: the model re-reads every tool result,
12+
> "fixes" your URLs, reorders your steps, and bills you for all of it.
13+
>
14+
> oya doesn't. The model writes a typed plan **once** — tool outputs never go back
15+
> through it.
16+
>
17+
> 5× fewer tokens than Mastra. Drop-in. 👇
18+
> github.com/oya-labs/oya
19+
20+
---
21+
22+
## Thread
23+
24+
**1/**
25+
> Your agent rewrites URLs, skips steps, and re-reads entire documents on every
26+
> turn. That's not a bug in your prompt — it's the architecture.
27+
>
28+
> Every framework (ReAct, LangGraph, Mastra, the Vercel AI SDK) is a *token loop*.
29+
> oya isn't. 🧵
30+
31+
**2/**
32+
> A token loop feeds every tool result back into the model to pick the next step.
33+
> So:
34+
> • it "normalises" URLs and UUIDs (state corruption)
35+
> • it reorders/skips dependent steps (ordering drift)
36+
> • it re-bills every byte at token prices (cost)
37+
>
38+
> Same root cause: the model reads state it never needed.
39+
40+
**3/**
41+
> oya is **plan, don't react**. The model emits ONE typed dataflow plan; a runtime
42+
> executes the DAG. Each value is shown to the model only at the level the plan
43+
> declares — `OPAQUE` by default (type + provenance, never the bytes).
44+
45+
**4/**
46+
> Because tool outputs are OPAQUE, an attacker who injects a payload into a fetched
47+
> page accomplishes nothing — the model never reads that handle. A whole class of
48+
> indirect prompt injection becomes *inexpressible*.
49+
50+
**5/**
51+
> Same task, same tools, real API, 3 trials (claude-opus-4-7):
52+
>
53+
> total tokens — Vercel 3,653 · Mastra 9,143 · **oya 1,783**
54+
> round-trips — 4 · 4 · **2** latency — 20s · 20s · **6.3s**
55+
>
56+
> ½ the tokens, 5× fewer than Mastra, ~3× faster — and deterministic.
57+
58+
**6/**
59+
> It's a **drop-in for Mastra** — change two imports:
60+
>
61+
> `@mastra/core` → `oya`
62+
>
63+
> Same createTool / Agent / generate(). It just plans instead of looping.
64+
65+
**7/**
66+
> Try it on your own agents:
67+
>
68+
> bun add oya
69+
> bunx oya dev # live studio: chat + the DAG executing, with per-node I/O
70+
>
71+
> MIT, TypeScript. github.com/oya-labs/oya ⭐
72+
73+
---
74+
75+
## Show HN
76+
77+
**Title:**
78+
> Show HN: oya – plan-don't-react agents (5× fewer tokens, injection-proof tools)
79+
80+
**First comment:**
81+
> Every agent framework I've used is a token loop: the model picks a tool, sees the
82+
> raw result, picks the next — so every URL, ID, and document flows back through the
83+
> model on each turn. That causes three things I kept hitting: the model rewrites
84+
> low-frequency strings (URLs/UUIDs), it reorders or skips dependent steps, and it
85+
> re-bills every intermediate byte.
86+
>
87+
> oya takes the database-optimizer approach instead: the model emits a typed
88+
> dataflow plan once, a runtime runs the DAG, and each value carries a *projection
89+
> level* deciding what the model may see — OPAQUE by default, so tool outputs never
90+
> re-enter the context. A nice side effect: indirect prompt injection through tool
91+
> output has nowhere to land (the model never reads those handles).
92+
>
93+
> It's a drop-in for Mastra (same createTool/Agent/generate), Bun-built, MIT. In a
94+
> 3-trial benchmark on Opus it used ~½ the tokens of the leanest token loop, 5×
95+
> fewer than Mastra, and ran ~3× faster with a fixed execution order. The gap
96+
> narrows on cheaper models and widens with bigger payloads — methodology and the
97+
> harness (vs the real Vercel AI SDK and Mastra) are in the repo so you can check.
98+
>
99+
> `bunx oya dev` opens a local studio that shows the plan executing live with
100+
> per-node I/O at each projection level. Would love feedback on the projection-type
101+
> model.
102+
103+
---
104+
105+
## One-liner descriptions
106+
107+
- GitHub "About": *Plan-don't-react agents for TypeScript. The model plans once; the runtime runs it; tool outputs never go back through the model. Drop-in for Mastra.*
108+
- npm: *A plan-don't-react framework for LLM agents — fewer tokens, deterministic, injection-safe by construction.*

‎Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@ dev: build-libs ## Start oya Studio (the Next.js playground) at http://localhost
2222
example: ## Run the weather example end-to-end (no network)
2323
cd packages/core && bun run example
2424

25+
demo: ## Play the paced terminal demo (for a GIF capture; no key)
26+
cd packages/core && bun run demo
27+
2528
test: ## Run the core test suite
2629
cd packages/core && bun test
2730

0 commit comments

Comments
 (0)