v0 SDK reference · 5 min

Install. Push. Query.

Install the beava server, install the Python SDK, push your first event and query the feature — in five minutes.

Pick a path

Most readers want the install path below; if you'd rather skip the server entirely and run beava in-process under your Python interpreter, embed mode is a one-line alternative.

01 Install beava

pip install beava drops a platform wheel from PyPI. The wheel ships the SDK and the Rust server binary together (~4 MB, polars / ruff / uv pattern). If you'd rather run the server in a container, Docker is the alternative.

pip install beava

# SDK + server binary land together; `beava` is on PATH
beava --data-dir ./.beava/
# → HTTP listen   : 127.0.0.1:8080
# → TCP listen    : 127.0.0.1:8081 (enabled=true)

# persistent volume keeps your features across restarts
docker run -d --name beava \
  -p 8080:8080 -p 8081:8081 \
  -v beava-data:/data \
  beavadev/beava:latest

# SDK install — same `pip install beava` works inside docker
# the bundled binary on PATH; pass an explicit URL to `bv.App(url=...)`.
curl -fsSL https://raw.githubusercontent.com/beava-dev/beava/main/scripts/install.sh | sh

# verify
curl -X POST http://localhost:8080/ping
# → {"pong":true,"registry_version":0}

02 Declare your first feature

beava is declarative. You write a Python class for the event source and a function for the table (the per-entity feature you want to query). Every operator works the same way: group_by(...).agg(name=bv.<op>(...)).

import beava as bv

@bv.event
class PageView:
    user_id: str
    path: str

@bv.table(key="user_id")
def UserStats(pv: PageView):
    return pv.group_by("user_id").agg(
        visits=bv.count(window="1h"),
    )

Register it once. The server picks it up live — no restart.

python -c "import beava as bv; from site_features import *; \
  bv.App('http://localhost:8080').register(PageView, UserStats)"
# → {"status": "ok", "registry_version": 1, "added": ["PageView", "UserStats"]}

03 Push events, read the feature

beava speaks HTTP — every operation is a single request. You can drive it from Python or from curl; the wire is identical.

curl -X POST \
  http://localhost:8080/push \
  -H "content-type: application/json" \
  -d '{
    "event": "PageView",
    "data": {
      "user_id": "alice",
      "path":    "/home"
    }
  }'

{
  "ack_lsn": 62,
  "idempotent_replay": false,
  "registry_version": 1
}

Now ask beava for the running feature:

curl -X POST \
  http://localhost:8080/get \
  -H "content-type: application/json" \
  -d '{
    "table": "UserStats",
    "key":   "alice"
  }'

{ "visits": 2 }

The /get response is the row itself — a flat dict of feature name → value. Cold-start (no events for that key) returns {}, not an error — a cold key is a key with no data.

App parameters

Every bv.App(...) accepts the same shape. Pass an explicit URL or rely on embed mode (no URL → spawn local binary on ephemeral ports).

Common questions

with bv.App() as app:
    app.register(PageView, UserStats)
    app.push("PageView", {"user_id": "alice", "path": "/home"})
    print(app.get("UserStats", "alice"))

Where to go next

You've got beava running and a counter ticking. Two reasonable next stops: