Guide for Coding Agents¶
This page is written for AI coding agents that write code using reaktiv. The
same guide ships inside the package as reaktiv/AGENTS.md, so it always
matches the installed version. To use it in your project, add a line like this
to your own AGENTS.md (or CLAUDE.md):
When writing code with reaktiv, follow the guide in the installed package:
python -c "import reaktiv, pathlib; print(pathlib.Path(reaktiv.__file__).with_name('AGENTS.md'))"
An index for agents is also available at /llms.txt.
reaktiv: guide for coding agents¶
Instructions for writing application code with reaktiv. This guide ships with the package and describes this installed version; its examples run in reaktiv's test suite. Follow it over patterns from other signal libraries or older reaktiv versions.
Mental model¶
State is a graph. Signals hold values you write. Computed values are pure functions of other signals: lazy, cached, recomputed only when a dependency changed. Effects are the edge of the graph, where changes leave it as side effects. Dependencies are tracked automatically: whatever a computed or effect reads while running becomes a dependency, and the set is rebuilt on every run.
Write code that declares relationships, not code that pushes updates
around. If a value can be derived, derive it with computed; never copy
it into another signal and keep it in sync by hand. Think of a spreadsheet:
signals are input cells, computed values are formulas, effects are what you
do with the results.
Push, then pull¶
A write runs in two phases:
- Push (notify).
set()stores the value and marks everything downstream as possibly stale. Nothing is recomputed yet; effects are only queued. - Pull (recompute on read). When an effect runs or anyone reads a computed, it checks whether its sources really changed and recomputes only then, sources first.
Consequences to rely on:
- Lazy: a computed nobody reads never runs, however often its inputs change. Several writes before the next read cost one recomputation.
- Glitch-free: in a diamond (
bandcboth derived froma, an effect reading all three) the effect runs once and sees consistent values, never a mix of old and new. - Equality cut-off: if a computed recomputes to an equal value, its
dependents are not rerun. The default comparison is identity (
is), which only catches the same object (and, by accident, small cached ints). For a filter in front of expensive work, compare values explicitly:computed(lambda: len(items()), equal=lambda a, b: a == b). - Effects run after the push, once per change (or once per outermost
batch()), usually on the thread that wrote (see "Threads and async").
Choose the primitive¶
| Need | Use |
|---|---|
| State you write | signal(value), or field(value) on a ReactiveModel |
| A value derived from other state | computed(fn) |
| Derived state the user can override until the source changes | linked(fn) |
| A side effect when state changes (I/O, logging, UI) | effect(fn) |
| Async loading driven by state, with status and cancellation | resource(params=..., loader=...) |
Consume changes in async for |
to_async_iter(sig) |
| A framework that schedules its own work | reaktiv.subtle.Watcher (not for app code) |
Use the lowercase factories (signal, computed, linked, effect,
resource, field). Uppercase names (Signal, ComputeSignal, ...) are for
type annotations; annotate parameters with ReadableSignal[T] or
WritableSignal[T] from reaktiv.
Core example¶
from reaktiv import batch, computed, effect, signal
price = signal(10.0)
quantity = signal(2)
total = computed(lambda: price() * quantity()) # derived, not stored
log = []
logger = effect(lambda: log.append(total())) # keep the reference!
with batch(): # several writes, one effect run
price.set(12.0)
quantity.update(lambda q: q + 1)
assert total() == 36.0
assert log == [20.0, 36.0]
logger.dispose()
Rules¶
- Read by calling:
count(). Write withcount.set(v)orcount.update(lambda v: v + 1). Onlysignal,fieldandlinkedare writable; computed signals have noset/update. - Keep computations pure. No I/O, no writes, no mutation inside
computedorlinkedfunctions. Writing a signal there raisesRuntimeError. Put side effects in effects. (An explicituntracked()block lifts the check, as in Angular, for rare cases such as initializing a signal lazily on first read; do not use it to hide side effects.) - Keep every effect referenced (variable, attribute, or model member) and
dispose()it when done. Signals hold effects weakly: an unreferenced effect is garbage collected and silently stops running. Effects declared with@effecton aReactiveModelare retained by the model. - Replace values, do not mutate them. Default equality is identity
(
is): mutating a list in place and setting the same object notifies nobody. Write new objects:items.update(lambda xs: [*xs, item]). - Equality is "same value, keep the old one". Pass
equal=for value comparison:signal([], equal=lambda a, b: a == b). WhenequalreturnsTrue, the previous value is kept and nobody is notified, for signals, computed and linked alike. - Read reactive inputs first, then act (see "Effects: read, then act"). Tracking is dynamic: a signal read only in a branch that was not taken is not a dependency until that branch runs, which is correct. What breaks effects is a read that never happens because the code raised or returned before it, or a hidden read inside a helper the effect calls.
- Use
untrackedto read without subscribing:untracked(other)orwith untracked(): .... - Use
batch()to group writes so effects run once with the final values. It is not a transaction: writes apply immediately and are not rolled back if the block raises. - Avoid effects that write their own inputs. An effect that writes a
signal it read runs again. For synchronous effects, a loop that keeps
changing its inputs raises
RuntimeErrorafter 100 runs within one flush; an async effect doing the same is not bounded and keeps rescheduling itself. Prefercomputedorlinked. - Errors propagate through reads. A failing computed raises on read and keeps raising the same error, without rerunning, until a dependency changes. An exception inside an effect is printed, not raised.
Effects: read, then act¶
Structure every effect in two parts. First read all the signals it reacts to
(that is the tracking phase). Then perform the side effect without tracking,
so helpers and callbacks it calls cannot subscribe the effect to signals by
accident. Keep decisions in computed values so the effect only acts.
from reaktiv import computed, effect, signal, untracked
user = signal("ada")
theme = signal("dark")
log_level = signal("info") # read by the logging helper below
sent = []
def send(message: str) -> None: # a helper that happens to read a signal
sent.append(f"[{log_level()}] {message}")
greeting = computed(lambda: f"hi {user()} ({theme()})") # decide in computed
def notify_user():
message = greeting() # 1. read: the only dependency
with untracked(): # 2. act: reads in here do not subscribe
send(message)
notifier = effect(notify_user)
log_level.set("debug") # not a dependency: no rerun
user.set("grace") # reruns once
assert sent == ["[info] hi ada (dark)", "[debug] hi grace (dark)"]
notifier.dispose()
- One effect per side-effect concern; split an effect that does unrelated things, so each reruns only for its own inputs.
- Return a cleanup callable (or accept an
on_cleanupparameter) for subscriptions, timers and handles; it runs before the next run and ondispose(). - Do not use an effect to compute a value for other code. If something should
read it, it is a
computed.
Designing state¶
- Store the minimum, derive the rest. Keep only source-of-truth values
in signals;
total,is_valid,visible_itemsarecomputed. - Make signals granular. One signal per independently changing value
(
first_name,last_name), not one dict for a whole form, so a change reruns only what reads it. Group with aReactiveModel, not a big value. - Prefer immutable values (tuples, frozen dataclasses), so replacing is natural and default identity equality is cheap and correct.
- Expose read-only views of internal state with
sig.as_readonly(), and change state through methods that write (withbatch()for several writes). - Test through values: write signals, then assert on computed values; dispose effects and models at the end of each test.
Patterns¶
Group related state in a model. Members are created per instance; @effect
members start when the model is created; dispose() stops everything, for
good: anything registered with model.own(obj) afterwards is disposed at
once. Do not copy models (copy.copy shares their signals); construct a new
one from the values.
from reaktiv import ReactiveModel, computed, effect, field, linked
class Cart(ReactiveModel):
items = field[tuple[str, ...]]((), equal=lambda a, b: a == b) # immutable
page_size = field(10)
@computed
def count(self) -> int:
return len(self.items())
@linked
def page(self) -> int: # user-selectable; resets to 1 when items change
return 1 if self.items() else 0
@effect
def report(self):
print(f"{self.count()} items")
return lambda: None # optional cleanup, runs before the next run
cart = Cart() # prints "0 items" (model effects start immediately)
cart.items.update(lambda xs: (*xs, "apple")) # prints "1 items"
cart.page.set(3)
cart.items.update(lambda xs: (*xs, "pear")) # prints "2 items"
assert (cart.count(), cart.page()) == (2, 1)
cart.dispose()
Derived state that the user may override, but which should keep or adapt the
override when the source changes, uses linked with a computation. previous
is None on the first run; previous.source has the source's type and
previous.value the linked value's type:
from typing import Optional
from reaktiv import PreviousState, linked, signal
options = signal(["s", "m", "l"])
def keep_valid(opts: list[str], previous: Optional[PreviousState[list[str], str]]) -> str:
if previous is not None and previous.value in opts:
return previous.value # keep the user's choice while it is still valid
return opts[0]
size = linked(source=options, computation=keep_valid)
size.set("l")
options.set(["m", "l", "xl"])
assert size() == "l"
options.set(["xs"])
assert size() == "xs"
Load async data from reactive parameters with resource. Create it while an
event loop is running. Returning None from params means "nothing to
load" (status IDLE). A parameter change cancels the previous load.
import asyncio
from reaktiv import ResourceStatus, resource, signal
async def main() -> None:
user_id = signal(1)
async def load_user(request):
await asyncio.sleep(0.01)
if request.cancellation.is_set(): # superseded by a newer request
return None
return {"id": request.params, "name": f"user {request.params}"}
user = resource(params=lambda: user_id(), loader=load_user)
await asyncio.sleep(0.05)
current = user.value() # raises while status is ERROR; None until loaded
if current is not None:
assert current["id"] == 1
user_id.set(2) # status LOADING, then RESOLVED
await asyncio.sleep(0.05)
assert user.status() == ResourceStatus.RESOLVED
user.dispose()
asyncio.run(main())
Read a resource with status(), value(), error(), is_loading(),
has_value(), or one consistent record with snapshot()() (immutable).
value() is typed Optional: check it for None (type checkers do not
narrow it after has_value()). A loaded value of None counts as "no value". Use reload() to refetch,
set() for a local value, cancel() to stop the current load, and dispose()
to stop the resource.
Threads and async¶
- Thread safety is on by default; signals can be read and written from any
thread. An effect runs on the thread that first schedules it: usually the
writing thread, but an effect already waiting in another thread's
batch()runs there, once, when that batch ends. - Async effects and resources belong to the event loop they were created on;
changes from other threads are handed to that loop. Call a resource's own
methods (
set,reload,cancel,dispose) on its loop. - Prefer
resourceor a sync effect that starts a task overasync defeffects, which are experimental.
Avoid¶
- Copying derived values into signals from effects (
total.set(a() + b())): usecomputed. - Calling
effect(...)without keeping the result. - Reading a signal without calling it (
if flag:is always true; writeif flag():). - Mutating containers stored in signals.
- Using
subtle.Watcher,current_consumerorsignal_versionin application code; they exist for framework integrations.