wickra

README

Wickra Gym — Go

Go bindings for wickra-gym — a deterministic, Gymnasium-compatible backtest environment — over the C ABI via cgo. A rollout is byte-identical to every other language binding.

Install

go get github.com/wickra-lib/wickra-gym-go

The native library (libwickra_gym) must be available at build and run time: place it under lib/<os>_<arch>/ (git-ignored; staged from a release) and add that directory to your library search path.

Usage

package main

import (
	"encoding/json"
	"fmt"

	wickra "github.com/wickra-lib/wickra-gym-go"
)

func main() {
	spec := `{"dataset_ref":"demo","symbol":"BTCUSDT",
	  "observation":{"features":[{"kind":"price","field":"close"}]},
	  "action_space":{"type":"discrete","n":3},
	  "reward":"pnl","episode":{"max_steps":256,"warmup":0}}`

	env, err := wickra.New(spec)
	if err != nil {
		panic(err)
	}
	defer env.Free()

	candles := make([]map[string]float64, 300)
	for i := range candles {
		p := 100.0 + float64(i)
		candles[i] = map[string]float64{"ts": float64(i), "open": p, "high": p, "low": p, "close": p}
	}
	load, _ := json.Marshal(map[string]any{"cmd": "load", "candles": candles})
	env.Command(string(load))

	reset, _ := env.Command(`{"cmd":"reset","seed":0}`)
	fmt.Println(reset)
	step, _ := env.Command(`{"cmd":"step","action":2}`)
	fmt.Println(step)
}

Commands: load, reset, step, spec, version. Domain errors come back as {"ok":false,"error":...}; a bad spec returns an error from New.

Header

include/wickra_gym.h is a copy of the canonical C ABI header (bindings/c/include/wickra_gym.h); CI fails if the two drift.

License

Dual-licensed under MIT or Apache-2.0, at your option.

Documentation

Overview

Package wickra provides Go bindings for wickra-gym — a deterministic, Gymnasium-compatible backtest environment — over the C ABI. Env forwards command JSONs to the core verbatim, so a rollout is byte-identical to every other language binding.

Index

• func Version() string
• type Env
  • func New(specJSON string) (*Env, error)
  • func (e *Env) Command(cmdJSON string) (string, error)
  • func (e *Env) Free()

Functions

func Version

func Version() string

Version returns the wickra-gym version string.

Types

type Env

type Env struct {
	// contains filtered or unexported fields
}

Env is a handle to a gym environment. Construct it with New, drive it with Command, and release it with Free.

func New

func New(specJSON string) (*Env, error)

New constructs an environment from an EnvSpec JSON string. It returns an error if the spec fails to parse or validate.

func (*Env) Command

func (e *Env) Command(cmdJSON string) (string, error)

Command applies a command JSON and returns the response JSON string. Domain errors are returned in-band as {"ok":false,"error":...}; only unusable arguments or a caught panic produce a Go error.

func (*Env) Free

func (e *Env) Free()

Free releases the environment handle. It is safe to call once.