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 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 ¶
Dial connects to an MCP endpoint (http://host:port/api/v1/mcp) as the client named name.
func (*Client) Call ¶
Call calls one tool and answers its text; a tool's refusal is an error with the text it refused with.
func (*Client) Instructions ¶
Instructions are the server's instructions, as an agent reads them on connecting.
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 ¶
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.
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).
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.