evaluate

package
v2.10.1 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package evaluate judges a change agents use the way docs/EVALUATING.md says: by criteria scored from the server and the trace, never from an agent's report, run after run on one frozen build, until enough pass in a row.

It reads the server through Server, a port its MCP client fills, and the trace as calls the trace port defines. A document's own criteria (a real organisation's charter, say) are a file kept beside its runs, never in this repository.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Check

type Check struct {
	Name string `json:"name"`
	Pass bool   `json:"pass"`
	Why  string `json:"why"`
}

Check is one criterion's result.

type Client

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

Client is a Server reached over MCP's streamable HTTP. It names itself in its User-Agent, as every client is named in the trace, so an evaluator's own calls are told apart from the agent's.

func Dial

func Dial(ctx context.Context, endpoint, name string) (*Client, error)

Dial connects to an MCP endpoint (http://host:port/api/v1/mcp) as the client named name.

func (*Client) Call

func (c *Client) Call(ctx context.Context, tool string, args map[string]any) (string, error)

Call calls one tool and answers its text; a tool's refusal is an error with the text it refused with.

func (*Client) Close

func (c *Client) Close() error

Close ends the session.

func (*Client) Instructions

func (c *Client) Instructions() string

Instructions are the server's instructions, as an agent reads them on connecting.

func (*Client) Tools

func (c *Client) Tools(ctx context.Context) ([][2]string, error)

Tools are the server's tools, each a name and its description.

type Criteria

type Criteria struct {
	// Name is what is being judged, for the report.
	Name string `json:"name"`
	// Agent is the name the agent under test gives the server (its
	// client's), whose calls the trace is read for.
	Agent string `json:"agent"`
	// Runs is how many fresh runs in a row must pass on one build.
	Runs int `json:"runs"`
	// WholeDocument: the agent brought the whole document, not a part.
	WholeDocument bool `json:"wholeDocument,omitempty"`
	// Proposed: the change set was proposed.
	Proposed bool `json:"proposed,omitempty"`
	// OneObjectiveEach: every project has exactly one objective.
	OneObjectiveEach bool `json:"oneObjectiveEach,omitempty"`
	// NoPeople: no record names a person by their title, nor any name
	// the document gives a person.
	NoPeople bool `json:"noPeople,omitempty"`
	// Structure is the layout the work must have, when given.
	Structure *Structure `json:"structure,omitempty"`
	// Totals are the least each list holds across every project
	// (deliverables, milestones, risks, kpis, ...).
	Totals map[string]int `json:"totals,omitempty"`
	// KPIs are the indicators that must exist, by name pattern, and the
	// names none may have.
	KPIs *KPIs `json:"kpis,omitempty"`
}

Criteria say what a passing run is, for one document. Every check is read from the server or the trace; a check left out is not scored.

func ReadCriteria

func ReadCriteria(path string) (Criteria, error)

ReadCriteria reads a criteria file.

type KPIs

type KPIs struct {
	Require []string `json:"require,omitempty"`
	Forbid  string   `json:"forbid,omitempty"`
}

KPIs are indicators by name pattern.

type Run

type Run struct {
	Name   string `json:"name"`
	Commit string `json:"commit"`
	Score  *Score `json:"score,omitempty"`
}

Run is one evaluation run: its name, the commit of the build it ran on, and its score once scored.

type Score

type Score struct {
	ChangeSet string       `json:"changeSet"`
	Checks    []Check      `json:"checks"`
	Pass      bool         `json:"pass"`
	Trace     trace.Report `json:"trace"`
}

Score is a run judged: each check, whether all passed, and the trace figures of the agent's own calls.

func ScoreRun

func ScoreRun(ctx context.Context, srv Server, c Criteria, changeSet string, calls []trace.Call, document string) (Score, error)

ScoreRun scores one run's change set against the criteria: the server for what was written, calls for what the agent did, and the document for the names it gives people.

func (Score) Passed

func (s Score) Passed() int

Passed is how many checks passed.

type Server

type Server interface {
	Call(ctx context.Context, tool string, args map[string]any) (string, error)
}

Server is what scoring needs of a Cartograph server: one tool call, answered as the tool's text, or an error the tool refused with.

type Streak

type Streak struct {
	Commit string `json:"commit"`
	InARow int    `json:"inARow"`
	Bar    int    `json:"bar"`
	Closed bool   `json:"closed"`
}

Streak is where a feature stands against its bar: the runs that pass in a row at the end, on the latest run's build, and whether that is enough to close it (docs/EVALUATING.md, Control).

func StreakOf

func StreakOf(runs []Run, bar int) Streak

StreakOf counts, from the latest run back, the scored runs that pass on the latest run's build. A run on another build, a failed run or one not yet scored ends the count: a change to the code resets it.

type Structure

type Structure struct {
	// Components are one pattern for each component project the main
	// project lists, matched by name; no more, no fewer.
	Components []string `json:"components"`
	// Operations are a pattern each for an operation that must exist;
	// others may.
	Operations []string `json:"operations,omitempty"`
	// ScopeOut is a pattern one of the main project's out-of-scope lines
	// must match.
	ScopeOut string `json:"scopeOut,omitempty"`
	// NotComponents is a pattern no component's name may match: a
	// workstream, a phase.
	NotComponents string `json:"notComponents,omitempty"`
}

Structure is the main project's components, the services the work hands over to, what it leaves out, and what no component may be.

Jump to

Keyboard shortcuts

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