bind

package
v0.1.15 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 5, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package bind chooses which of a client's tools a declared capability binds to when the client gives no input schema to check a contract against.

Where a schema IS available the satisfaction rule (package satisfy) decides and this package is not used.

Everything here is normative: two runners must reach the same choice from the same inventory, so nothing depends on map order, inventory order or locale. Change the arithmetic and you change what every primitive binds to.

Index

Constants

View Source
const Floor = 0.60

Floor is the minimum score that binds. Chosen from measurement against two clients' real inventories; see bind_test.go.

Variables

This section is empty.

Functions

func Candidates

func Candidates(capability string, declared Effect, inventory []Tool) (Choice, []Candidate)

Candidates returns the choice Resolve makes, and with it every tool whose name clears the floor, best first. A caller that can also check a tool's schema walks the list and takes the first that passes.

func Rank

func Rank(e Effect) int

Rank orders effects by how much they can change. Unknown ranks lowest and must never be compared as if it were a statement.

func Tokens

func Tokens(name string) []string

Tokens splits a name into lower-case words on every non-alphanumeric rune and on a lower-to-upper case change, then reduces each word to a singular and each verb to its group's first word.

Types

type Candidate

type Candidate struct {
	Tool  Tool
	Score float64
}

Candidate is one tool that could be meant, with how close its name is.

type Choice

type Choice struct {
	Bound         *Tool
	Score         float64
	RunnerUp      *Tool // nil when there was no second candidate
	RunnerUpScore float64
	// Gated is set when the bound tool's server did not say what it does. The
	// runner treats it as a write whatever the primitive declared.
	Gated bool
	// Refused says why nothing bound. Empty when Bound is set.
	Refused string
}

Choice is the outcome for one declared capability.

func Resolve

func Resolve(capability string, declared Effect, inventory []Tool) Choice

Resolve binds one capability against an inventory.

A capability is written provider.resource.verb, for example gmail.threads.search. Its first part is the provider and its last the verb.

type Effect

type Effect string

Effect is what a primitive declares for a tool, and what a tool's own server says about it. Unknown is only ever the second.

const (
	Read        Effect = "read"
	Write       Effect = "write"
	Destructive Effect = "destructive"
	Unknown     Effect = "unknown"
)
const (
	Financial     Effect = "financial"
	IdentityAdmin Effect = "identity-admin"
)

Financial and IdentityAdmin are effect classes a primitive may declare. No client annotates a tool with either, so for comparing against an annotation they stand with Destructive.

type Tool

type Tool struct {
	Server    string
	Name      string
	Annotated Effect // what the server says; Unknown when it says nothing
	// Schema is the tool's input schema, where the client gives one. Binding
	// by name does not read it.
	Schema map[string]any `json:"-"`
}

Tool is one entry of a client's inventory, as its bridge reports it.

Jump to

Keyboard shortcuts

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