wire

package

v0.2.0 Latest Latest Go to latest Published: May 18, 2026 License: MIT Imports: 14 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/blackwell-systems/knowing

Links

Open Source Insights

Documentation ¶

Overview ¶

Package wire implements the GCF (Graph Compact Format) encoder and decoder.

GCF is a compact, text-only, graph-native wire format designed for MCP tool responses. It exploits referential identity (local IDs), graph topology (edges as references), and hierarchical grouping (distance-based sections) to achieve 35-50% token savings over JSON while remaining human-readable.

TOON (Token-Oriented Object Notation) encoder for knowing context output. Uses the official toon-format/toon-go library for spec-conformant encoding.

TOON is a compact, human-readable format designed for LLM contexts. It uses tabular arrays (header + rows) for uniform object collections, which is ideal for symbol lists where every entry has the same fields.

Spec: https://github.com/toon-format/spec Library: https://github.com/toon-format/toon-go

Index ¶

func Encode(p *Payload) string
func EncodeTOON(p *Payload) (string, error)
func EncodeWith(name string, p *Payload) (string, error)
func EncodeWithSession(p *Payload, sess *Session) string
func ListNames() string
func Register(c *Codec)
type Codec
- func Get(name string) (*Codec, error)
- func List() []*Codec
type Components
type Decoder
type Edge
type Encoder
type Payload
type Session
- func NewSession() *Session
type Symbol

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Encode ¶

func Encode(p *Payload) string

Encode serializes a Payload into GCF text format.

func EncodeTOON ¶ added in v0.2.0

func EncodeTOON(p *Payload) (string, error)

EncodeTOON encodes a Payload into TOON format using the official library.

func EncodeWith ¶

func EncodeWith(name string, p *Payload) (string, error)

EncodeWith encodes a payload using the named codec.

func EncodeWithSession ¶

func EncodeWithSession(p *Payload, sess *Session) string

EncodeWithSession encodes a payload using GCF with session deduplication. Symbols that were already transmitted in prior responses are emitted as bare references (`@N # previously transmitted`) instead of full declarations. After encoding, newly-sent symbols are recorded in the session.

func ListNames ¶

func ListNames() string

ListNames returns all registered codec names in sorted order.

func Register ¶

func Register(c *Codec)

Register adds a codec to the registry. Panics on duplicate name.

Types ¶

type Codec ¶

type Codec struct {
	Name        string
	Description string
	Encode      Encoder
	Decode      Decoder
}

Codec is a registered encoding scheme with encode/decode functions and metadata.

func Get ¶

func Get(name string) (*Codec, error)

Get returns the codec for the given name, or an error if not found.

func List ¶

func List() []*Codec

List returns all registered codecs.

type Components ¶

type Components struct {
	BlastRadius float64
	Confidence  float64
	Recency     float64
	Distance    float64
}

Components holds the score breakdown for a symbol.

type Decoder ¶

type Decoder func(input string) (*Payload, error)

Decoder parses a wire format string back into a Payload.

type Edge ¶

type Edge struct {
	Source   string // qualified name of source symbol
	Target   string // qualified name of target symbol
	EdgeType string
	Status   string // optional: "added", "removed", "unchanged" (for diff responses)
}

Edge represents a directed relationship in a GCF payload.

type Encoder ¶

type Encoder func(p *Payload) (string, error)

Encoder serializes a Payload into a wire format string.

type Payload ¶

type Payload struct {
	Tool        string
	TokensUsed  int
	TokenBudget int
	Symbols     []Symbol
	Edges       []Edge
}

Payload is the input/output structure for GCF encoding/decoding.

func Decode ¶

func Decode(input string) (*Payload, error)

Decode parses GCF text back into a Payload.

func DecodeWith ¶

func DecodeWith(name string, input string) (*Payload, error)

DecodeWith decodes input using the named codec.

func FromContextBlock ¶

func FromContextBlock(ctx stdctx.Context, block *knowingctx.ContextBlock, tool string, store types.GraphStore) (*Payload, error)

FromContextBlock converts a ContextBlock into a wire.Payload, optionally querying the store for edges between the included symbols.

type Session ¶

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

Session tracks symbols that have been transmitted to a client, enabling subsequent responses to reference them by ID without full retransmission. This makes multi-call workflows progressively cheaper.

Thread-safe: multiple tool handlers may encode concurrently within a session.

func NewSession ¶

func NewSession() *Session

NewSession creates a new empty session.

func (*Session) GetID ¶

func (s *Session) GetID(qname string) int

GetID returns the session-global ID for a previously transmitted symbol. Returns -1 if not found.

func (*Session) Record ¶

func (s *Session) Record(symbols []Symbol)

Record marks symbols as transmitted and assigns session-global IDs. Call this after a successful encode to register newly-sent symbols.

func (*Session) Reset ¶

func (s *Session) Reset()

Reset clears the session state.

func (*Session) Size ¶

func (s *Session) Size() int

Size returns the number of symbols tracked in this session.

func (*Session) Transmitted ¶

func (s *Session) Transmitted(qname string) bool

Transmitted returns true if the symbol has been sent in a previous response.

type Symbol ¶

type Symbol struct {
	QualifiedName string
	Kind          string
	Score         float64
	Provenance    string
	Distance      int
	Signature     string
	Components    Components
}

Symbol represents a node in a GCF payload.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL