Documentation
¶
Overview ¶
Package longsession writes a long Pi session fixture: a version 3 session file whose active context holds a chosen number of tokens, the agent directory that declares a scripted model with a chosen context window, and a metadata record. Pi, PiG and any harness that reads Pi session files open the same file, so memory measured with a loaded session compares like with like.
Tokens are counted as Pi's compaction.ts estimateTokens counts them: a quarter of the characters of each message's text, tool-call name and JSON arguments, and tool-result text, rounded up. All text is ASCII, so characters equal UTF-16 code units. Each assistant message reports usage whose input is the context before it, so the footer and the context gauge read the size the file holds.
A turn is a user prompt, an assistant message with a read tool call, the tool result (ResultBytes of source-like text), and an assistant answer. Content is pseudo-random from a fixed seed, so a size and seed always produce the same bytes.
Index ¶
Constants ¶
const ( Provider = "longsession" Model = "scripted" )
Provider and Model name the scripted model the fixture's agent directory declares and its assistant messages carry.
Variables ¶
This section is empty.
Functions ¶
func GenerateTree ¶
func GenerateTree(w io.Writer, opts TreeOptions) error
GenerateTree writes a session whose entries branch from earlier entries and include compactions, branch summaries, labels, custom entries, custom messages, session names, model and thinking-level changes, tool calls and results, extra members Pi does not read, and members written in an unusual order. Every entry's JSON is written by hand, so the file holds spellings JSON.stringify would not produce (escaped non-ASCII, exponent numbers, spaces).
Types ¶
type Meta ¶
type Meta struct {
Tokens int `json:"tokens"`
Target int `json:"target"`
Window int `json:"window"`
Turns int `json:"turns"`
Entries int `json:"entries"`
Bytes int64 `json:"bytes"`
ResultBytes int `json:"resultBytes"`
Seed uint64 `json:"seed"`
SHA256 string `json:"sha256"`
// ContentSHA256 hashes the entries without the header line, whose working directory differs per fixture directory: it identifies the conversation across machines.
ContentSHA256 string `json:"contentSha256"`
Cwd string `json:"cwd"`
Session string `json:"session"`
AgentDir string `json:"agentDir"`
Provider string `json:"provider"`
Model string `json:"model"`
}
Meta describes a written fixture.
func Generate ¶
Generate writes the session file to w and returns its metadata without the byte count, hash or paths.
func Write ¶
Write creates dir/session.jsonl, dir/agent/models.json, dir/agent/settings.json, dir/meta.json and the working directory dir/work.
func (Meta) Stage ¶
Stage copies the fixture's session file to dir/session.jsonl and returns that path. A harness appends every prompt it answers to the session it opened, so each measurement opens its own copy and the fixture keeps the bytes meta.json describes. Stage fails when the fixture no longer matches its recorded SHA256.
type Options ¶
type Options struct {
// Tokens is the context size to reach, by Pi's estimate. Generation stops at the first turn boundary at or above it.
Tokens int
// Window is the model's declared context window in tokens.
Window int
// ResultBytes is the size of each tool result. Zero means 16384.
ResultBytes int
// Seed selects the content. Sizes with the same seed share their leading turns.
Seed uint64
// Cwd is the session's working directory. Write uses dir/work and creates it; Generate uses /longsession when empty.
Cwd string
// BaseURL is the scripted model's OpenAI-compatible endpoint written to models.json. Empty means http://127.0.0.1:9/v1, which refuses connections.
BaseURL string
}
Options selects a fixture.
type TreeOptions ¶
type TreeOptions struct {
// Entries is the number of entries after the header.
Entries int
// Seed selects the shape and the text; one seed always produces the same file.
Seed uint64
// Cwd is the header's working directory.
Cwd string
// ForkOneIn makes one entry in this many branch from an earlier entry. Zero means 6, which gives a session with a leaf for every few entries; a large value gives a long conversation with a few branches.
ForkOneIn int
}
TreeOptions shapes a session that exercises every entry type of a Pi v3 session file rather than one long conversation.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
longsession
command
Command longsession writes long Pi session fixtures and measures a harness's memory with one loaded.
|
Command longsession writes long Pi session fixtures and measures a harness's memory with one loaded. |