core

Overview ¶

Package core is the module overview for the Scope narrow waist. It declares no API of its own; every capability lives in a sibling package listed below.

Core owns the serializable, provider-neutral protocols that every provider implements and every capability module consumes: the protocol values, the minimal calling SPI of each modality, and the pure composition around them. It owns no provider SDK, no network backend, no tokenizer vocabulary, no agent control flow, and no telemetry.

Protocol packages ¶

Each modality package owns one request/response protocol and the minimal github.com/Tangerg/scope/core/chat.Model-shaped SPI that carries it:

• chat: messages, parts, tool calls, usage, and output format.
• embedding: text-to-vector requests and vectors.
• image: image generation.
• moderation: content classification.
• rerank: query-to-document relevance ranking.
• speech: text-to-speech, with an independent Streamer.
• transcription: audio-to-text.

Every one of them exports the same three sentinels — ErrInvalidOptions, ErrInvalidRequest, and ErrInvalidResponse — so providers and integrations classify failures identically. Chat extends that triple with its own protocol errors because its wire additionally models tool calls, parts, and usage. Classify protocol errors with errors.Is; never match on message text. Chat's invocation.Failure owns execution evidence for one complete model invocation. Its ClassifyFailure function preserves that scope across composed calls while errors.Is and errors.As retain the underlying diagnostics. JSON decoders reject unknown struct members before replacing the receiver, including nested protocol values. Metadata, namespaced extensions, JSON schemas, and tool-defined payloads retain their open data contracts. Protocol validation rejects strings and timestamps that cannot be encoded losslessly, so accepted values can cross the JSON boundary without repair.

Shared values ¶

The content, document, media, and metadata packages own the values the protocols embed: ordered text/media blocks and citations, the canonical Document, the Media container shared by every modality, and the JSON-safe typed extension values. The timestamp package owns lossless JSON admission for time.Time without introducing a competing time representation. A protocol DTO never carries a closure, reader, logger, tracer, registry, or native client.

Cross-protocol capabilities ¶

The jsonschema, tool, tokenizer, history, and vectorstore packages own the capabilities that are not specific to one modality: schema derivation and validation, the executable tool contract with its binding and authorization boundary, token counting and encoding, conversation history, and semantic indexing and search.

Direct clients ¶

The chatclient and embeddingclient packages add the ordinary-path conveniences — request admission, prompt templates, and structured output — without changing the SPI; chat.Wrap is the one way to compose middleware. Option defaults stay with the provider that owns them. The safeguard package screens input and output as fail-closed chat middleware. The httpclient package binds a borrowed HTTP client to its configured API origin so credentials cannot cross that boundary through redirects. The Host retains transport, retry, authentication, and resource-lifetime ownership.

Streaming ¶

A modality's Model has only Call. Real streaming is a separate Streamer, so a provider that cannot stream never has to pretend it can. Streams are iter.Seq2 values; early caller stop, context cancellation, and first-error termination are all part of the contract.

Reference implementations and contract suites ¶

The history/inmemory and vectorstore/inmemory packages are in-process reference stores. The modeltest, history/storetest, and vectorstore/storetest packages hold the reusable conformance suites an implementor runs to be held to the same protocol as every other provider. They contain no provider implementation and are never a dependency of production code.

Boundaries ¶

Core never imports a sibling module, a provider SDK, a concrete tokenizer vocabulary, or OpenTelemetry. Instrumentation lives in the otel module and decorates Core from the outside. Retries, approvals, planning, and durable execution are Agent or Host concerns.

package main

import (
	"context"
	"fmt"

	"github.com/Tangerg/scope/core/chat"
	"github.com/Tangerg/scope/core/chatclient"
)

type echoModel struct{}

func (echoModel) Call(_ context.Context, request *chat.Request) (*chat.Response, error) {
	message := chat.NewAssistantMessage(chat.NewTextPart(request.Messages[0].Text()))
	output, err := chat.NewOutput(&message, chat.FinishReasonStop, nil)
	if err != nil {
		return nil, err
	}
	return chat.NewResponse(output, nil)
}

func main() {
	client, err := chatclient.New(echoModel{})
	if err != nil {
		panic(err)
	}

	request := &chat.Request{
		Messages: []chat.Message{
			chat.NewUserMessage(chat.NewTextPart("hello")),
		},
		Options: chat.Options{Model: "example-model"},
	}
	response, err := client.Call(context.Background(), request)
	if err != nil {
		panic(err)
	}

	fmt.Println(response.Text())
}

Output:
hello