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 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)
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 ¶
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, metadata *ResponseMetadata) (*Response, error)
func (Response) MarshalJSON ¶
func (*Response) UnmarshalJSON ¶
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"`
// Created is the provider-reported creation time, Unix seconds.
Created int64 `json:"created"`
// 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