knowledge

package
v0.1.0-round1 Latest Latest
Warning

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

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

Documentation

Overview

Package knowledge defines SyncBase's document, version, processing, and search contracts.

Index

Constants

View Source 
const (
	// VectorDimension is the only supported embedding dimension for the active profile.
	VectorDimension = 384
	// MaxUploadBytes is the maximum accepted PDF size.
	MaxUploadBytes = 100 * 1024 * 1024
	// MaxPDFPages is the maximum accepted page count.
	MaxPDFPages = 500
)

Variables

View Source 
var (
	// ErrInvalidArgument reports a caller contract violation.
	ErrInvalidArgument = errors.New("invalid argument")
	// ErrUnauthenticated reports missing or invalid credentials.
	ErrUnauthenticated = errors.New("unauthenticated")
	// ErrTemporarilyUnavailable reports a retryable dependency failure.
	ErrTemporarilyUnavailable = errors.New("temporarily unavailable")
	// ErrProfileMismatch reports incompatible processing or search profiles.
	ErrProfileMismatch = errors.New("profile mismatch")
	// ErrNotFound reports a missing document or version.
	ErrNotFound = errors.New("not found")
	// ErrQueueFull reports bounded processing-queue exhaustion.
	ErrQueueFull = errors.New("queue full")
	// ErrIdempotencyConflict reports reuse of a key for different input.
	ErrIdempotencyConflict = errors.New("idempotency conflict")
	// ErrStaleFence reports work attempted by an expired processing owner.
	ErrStaleFence = errors.New("stale fence")
	// ErrInvalidPDF reports a PDF that violates the supported input contract.
	ErrInvalidPDF = errors.New("invalid PDF")
)

Functions

func ScoreFromCosineDistance 

func ScoreFromCosineDistance(distance float64) float64

ScoreFromCosineDistance maps pgvector cosine distance to the stable public score.

Types

type Checkpoint 

type Checkpoint struct {
	RunID         uuid.UUID
	Stage         Stage
	InputSHA256   string
	OutputSHA256  string
	FormatVersion string
	ArtifactKey   string
	ArtifactSize  int64
	FencingToken  int64
	CompletedAt   time.Time
}

Checkpoint identifies a content-verified intermediate pipeline artifact. InputSHA256 chains stages together so output from a different original or processing profile can never be resumed accidentally.

type Chunk 

type Chunk struct {
	Index      int    `json:"chunk_index"`
	PageNumber int    `json:"page_number"`
	Text       string `json:"text"`
}

Chunk is one page-bounded searchable passage.

type ClaimedRun 

type ClaimedRun struct {
	RunID              uuid.UUID
	DocumentID         uuid.UUID
	VersionID          uuid.UUID
	Version            int
	StorageKey         string
	ContentSHA256      string
	ProfileFingerprint string
	Fence              int64
	AutomaticAttempt   int
}

ClaimedRun carries the immutable identity and fencing token for leased work.

type DocumentDetails 

type DocumentDetails struct {
	ID            uuid.UUID
	Name          string
	ActiveVersion *int
	Versions      []VersionView
}

DocumentDetails contains a logical document and newest-first version history.

type DocumentName 

type DocumentName struct {
	Display    string
	Normalized string
}

DocumentName is the user-visible name and its comparison key.

func NewDocumentName 

func NewDocumentName(value string) (DocumentName, error)

NewDocumentName validates and normalizes a document name.

type DocumentSummary 

type DocumentSummary struct {
	ID            uuid.UUID
	Name          string
	ActiveVersion *int
	LatestVersion int
	LatestStatus  VersionStatus
	UpdatedAt     time.Time
}

DocumentSummary is the list projection for one logical document.

type IndexedChunk 

type IndexedChunk struct {
	Chunk
	Snippet   string    `json:"snippet"`
	Embedding []float32 `json:"embedding"`
}

IndexedChunk adds a public snippet and embedding to a chunk.

type PageText 

type PageText struct {
	PageNumber int    `json:"page_number"`
	Text       string `json:"text"`
}

PageText is normalized text extracted from one PDF page.

type Profile 

type Profile struct {
	Fingerprint        string
	ParserID           string
	ChunkerID          string
	Provider           string
	EmbeddingModelID   string
	ONNXRuntimeID      string
	VectorDimension    int
	Distance           string
	ChunkSizeTokens    int
	ChunkOverlapTokens int
	MinimumScore       float64
}

Profile is the immutable parser, chunker, embedding, and ranking contract.

func NewProfile 

func NewProfile(modelSHA256, tokenizerSHA256, onnxRuntimeID string, minimumScore float64) (Profile, string, error)

NewProfile builds the immutable Go processing profile and canonical representation.

type RegisterCommand 

type RegisterCommand struct {
	RequestKey       string
	Operation        RegistrationOperation
	TargetDocumentID *uuid.UUID
	DocumentName     DocumentName
	ContentSHA256    string
	ByteSize         int64
	OriginalFileName string
	StorageKey       string
}

RegisterCommand is the validated persistence command for one uploaded PDF.

type Registration 

type Registration struct {
	DocumentID uuid.UUID
	VersionID  uuid.UUID
	Version    int
	RunID      uuid.UUID
	Status     VersionStatus
	Recovered  bool
}

Registration identifies the version and processing run created by an upload.

type RegistrationOperation 

type RegistrationOperation string

RegistrationOperation distinguishes new documents from new versions. 

const (
	// RegisterNewDocument creates a logical document and version one.
	RegisterNewDocument RegistrationOperation = "NEW_DOCUMENT"
	// RegisterNewVersion appends the next version to an existing document.
	RegisterNewVersion RegistrationOperation = "NEW_VERSION"
)

type ReserveUploadCommand 

type ReserveUploadCommand struct {
	RequestKey       string
	Operation        RegistrationOperation
	TargetDocumentID *uuid.UUID
	ContentSHA256    string
	ByteSize         int64
}

ReserveUploadCommand is the durable idempotency identity written before PDF parsing or Original storage begins.

type RunStatus 

type RunStatus string

RunStatus is the durable lifecycle state of one processing run. 

const (
	// RunQueued is eligible for a processing lease.
	RunQueued RunStatus = "QUEUED"
	// RunRunning currently owns or awaits recovery of a lease.
	RunRunning RunStatus = "RUNNING"
	// RunSucceeded activated its version.
	RunSucceeded RunStatus = "SUCCEEDED"
	// RunFailed exhausted its permitted recovery path.
	RunFailed RunStatus = "FAILED"
	// RunSuperseded completed after a newer version was already active.
	RunSuperseded RunStatus = "SUPERSEDED"
)

type SearchHit 

type SearchHit struct {
	Rank            int       `json:"rank"`
	Score           float64   `json:"score"`
	DocumentID      uuid.UUID `json:"document_id"`
	DocumentName    string    `json:"document_name"`
	VersionID       uuid.UUID `json:"version_id"`
	DocumentVersion int       `json:"document_version"`
	PageNumber      int       `json:"page_number"`
	Snippet         string    `json:"snippet"`
	SourceURL       string    `json:"source_url"`
	// StorageKey and ContentSHA256 are private retrieval-safety inputs. They
	// intentionally never cross the JSON/public runtime boundary.
	StorageKey    string `json:"-"`
	ContentSHA256 string `json:"-"`
}

SearchHit is one ranked, page-grounded result from an active version.

type SourceDocument 

type SourceDocument struct {
	DocumentID uuid.UUID
	Name       string
	VersionID  uuid.UUID
	Version    int
	StorageKey string
	// ContentSHA256 is the immutable digest used to verify the original before
	// source metadata or bytes are served.
	ContentSHA256 string
	PageCount     int
}

SourceDocument identifies the immutable original for one version.

type Stage 

type Stage string

Stage identifies one checkpointed processing phase. 

const (
	// StageMetadata initializes a claimed run.
	StageMetadata Stage = "METADATA"
	// StageParse extracts page-scoped text.
	StageParse Stage = "PARSE"
	// StageChunk creates page-bounded passages.
	StageChunk Stage = "CHUNK"
	// StageEmbed creates pinned-profile vectors.
	StageEmbed Stage = "EMBED"
	// StageStore persists staged search chunks.
	StageStore Stage = "STORE"
	// StageActivate atomically publishes the completed version.
	StageActivate Stage = "ACTIVATE"
)

func ProcessingStages 

func ProcessingStages() []Stage

ProcessingStages returns the processing stages in execution order.

type UploadRecovery 

type UploadRecovery struct {
	State        UploadRecoveryState
	Registration Registration
}

UploadRecovery returns a recovery state and accepted registration when present.

type UploadRecoveryState 

type UploadRecoveryState string

UploadRecoveryState describes the durable outcome of an idempotent upload key. 

const (
	// UploadNotCommitted means no durable request exists for the key.
	UploadNotCommitted UploadRecoveryState = "not_committed"
	// UploadPending means registration has not reached a durable outcome.
	UploadPending UploadRecoveryState = "pending"
	// UploadAccepted means registration committed successfully.
	UploadAccepted UploadRecoveryState = "accepted"
	// UploadConflict means the key was reused for different input.
	UploadConflict UploadRecoveryState = "conflict"
	// UploadExpired means the recovery window has elapsed.
	UploadExpired UploadRecoveryState = "expired"
)

type VersionStatus 

type VersionStatus string

VersionStatus is the durable lifecycle state of one document version. 

const (
	// VersionQueued is awaiting a processing lease.
	VersionQueued VersionStatus = "QUEUED"
	// VersionProcessing is owned by a live or recoverable processing run.
	VersionProcessing VersionStatus = "PROCESSING"
	// VersionActive is the only version exposed to search.
	VersionActive VersionStatus = "ACTIVE"
	// VersionFailed requires automatic or manual recovery.
	VersionFailed VersionStatus = "FAILED"
	// VersionSuperseded has been replaced by a newer active version.
	VersionSuperseded VersionStatus = "SUPERSEDED"
)

type VersionView 

type VersionView struct {
	ID                   uuid.UUID
	VersionNumber        int
	Status               VersionStatus
	Active               bool
	Stage                Stage
	RunID                uuid.UUID
	ActivationOutcome    string
	ErrorCode            string
	CorrelationID        string
	AutomaticAttempts    int
	NextAutomaticRetryAt *time.Time
	ManualRetryAllowed   bool
	QueuePosition        int
	PageCount            int
	CreatedAt            time.Time
	UpdatedAt            time.Time
}

VersionView is the administrator projection for one document version.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.