Documentation
¶
Overview ¶
Package moderation defines the serializable content-moderation protocol and its single-method Model capability.
A Request can classify multiple texts. Each Output retains provider category names and their Verdict values, while Categories.Flagged provides the aggregate decision. Provider-only options use Options.SetExtension so Extensions remains JSON-safe; Request has no arbitrary parameter bag. Implementations and defaults live outside Core.
Example ¶
package main
import (
"fmt"
"github.com/Tangerg/scope/core/moderation"
)
func main() {
request, err := moderation.NewRequest([]string{"content to classify"})
if err != nil {
panic(err)
}
options := moderation.Options{Model: "moderation-model"}
err = options.Validate()
if err != nil {
panic(err)
}
request.Options = options
categories := moderation.Categories{
"violence": {Flagged: true, Score: 0.91},
}
fmt.Println(request.Options.Model, categories.Flagged())
}
Output: moderation-model true
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
This section is empty.
Types ¶
type Categories ¶
Categories is the provider-reported category set. Keys retain provider semantics instead of forcing every provider through one closed taxonomy; Flagged collapses the open set only when a caller needs a yes/no policy gate.
func (Categories) Flagged ¶
func (c Categories) Flagged() bool
func (Categories) MarshalJSON ¶
func (c Categories) MarshalJSON() ([]byte, error)
func (*Categories) UnmarshalJSON ¶
func (c *Categories) UnmarshalJSON(data []byte) error
type Model ¶
type Model interface {
// Call classifies one validated input batch without retaining or mutating the
// request. Outputs preserve input order, the returned response belongs to the
// caller, and context cancellation remains identifiable through errors.Is.
Call(ctx context.Context, request *Request) (*Response, error)
}
Model is the complete provider-neutral moderation SPI. Call implementations validate requests before I/O, reject explicit options they cannot represent, preserve context error identity, and return responses that pass Validate. Provider defaults and identity belong to provider construction and observability.
type ModelFunc ¶
ModelFunc lets an ordinary function satisfy Model without declaring a named type, which is what keeps middleware and test doubles from each inventing their own adapter.
type Options ¶
type Options struct {
// Model is the provider model identifier.
Model string `json:"model"`
// Extensions carries JSON-safe provider-specific options unknown to this
// struct.
Extensions metadata.Extensions `json:"extensions,omitzero"`
}
Options holds per-request moderation configuration. Resolve overlays only explicitly supplied values, merges namespaced extensions, and never aliases mutable data from either input.
func (Options) MarshalJSON ¶
func (*Options) UnmarshalJSON ¶
type Output ¶
type Output struct {
// Categories holds the per-category verdict.
Categories Categories `json:"categories,omitzero"`
// Metadata carries per-input extras.
Metadata metadata.Map `json:"metadata,omitzero"`
}
Output is one input's moderation verdict plus metadata.
func NewOutput ¶
func NewOutput(categories Categories, outputMetadata metadata.Map) (*Output, error)
NewOutput validates and snapshots one provider result before it enters a Response.
func (Output) MarshalJSON ¶
func (*Output) UnmarshalJSON ¶
type Request ¶
type Request struct {
// Texts is the input list. Each entry is moderated independently.
Texts []string `json:"texts,omitzero"`
Options Options `json:"options,omitzero"`
}
Request is one moderation call: the input texts and explicit options.
func NewRequest ¶
NewRequest preserves the provider-neutral batch shape and clones the input, so later caller mutation cannot change a request already in flight.
func (Request) MarshalJSON ¶
func (*Request) UnmarshalJSON ¶
type Response ¶
type Response struct {
// Outputs holds one entry per input, in the same order.
Outputs []*Output `json:"outputs,omitzero"`
// Metadata carries shared response-level fields.
Metadata *ResponseMetadata `json:"metadata,omitempty"`
}
Response is the full moderation output: one *Output per input plus shared response metadata.
func NewResponse ¶
func NewResponse(outputs []*Output, responseMetadata *ResponseMetadata) (*Response, error)
NewResponse validates a complete provider result at the protocol boundary.
func (Response) MarshalJSON ¶
func (*Response) UnmarshalJSON ¶
func (*Response) ValidateFor ¶ added in v0.16.0
ValidateFor checks a provider result against the request it answers.
Outputs declares one entry per input in the same order, and here the correspondence decides what a caller allows and blocks: a result short of the inputs leaves the last text unmoderated while every earlier verdict still looks well formed, and there is no field on an Output tying it back to a text. Validate cannot see it, because the input count is not part of the response, so this is the check that keeps a moderation verdict attached to the text it judged.
type ResponseMetadata ¶
type ResponseMetadata struct {
// ID is the provider-assigned response id.
ID string `json:"id"`
// Model is the model name actually served.
Model string `json:"model"`
// CreatedAt is the provider-reported creation timestamp.
CreatedAt time.Time `json:"created_at,omitzero"`
// Extra carries JSON-safe provider-specific metadata.
Extra metadata.Map `json:"extra,omitzero"`
}
ResponseMetadata holds response-level metadata for a moderation call.
func (ResponseMetadata) MarshalJSON ¶
func (r ResponseMetadata) MarshalJSON() ([]byte, error)
func (*ResponseMetadata) UnmarshalJSON ¶
func (r *ResponseMetadata) UnmarshalJSON(data []byte) error
type Verdict ¶
type Verdict struct {
// Flagged is true when the content violates this category's policy.
Flagged bool `json:"flagged"`
// Score is the provider's confidence in the violation, 0–1.
Score float64 `json:"score"`
}
Verdict is one moderation dimension's outcome — a flagged bit plus a confidence score in [0, 1].
Source Files