entity

package
v0.8.2 Latest Latest
Warning

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

 Go to latest Published: Feb 12, 2026 License: AGPL-3.0 Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	RelationSynonym     = "SYNONYM"
	RelationAntonym     = "ANTONYM"
	RelationHypernym    = "HYPERNYM" // is-a (parent/superordinate)
	RelationHyponym     = "HYPONYM"  // is-a (child/subordinate)
	RelationAssociation = "ASSOCIATION"
	RelationCauseEffect = "CAUSE_EFFECT"
	RelationPartWhole   = "PART_WHOLE"
	RelationDerivative  = "DERIVATIVE"

	// WordNet-specific relations
	RelationMemberHolonym  = "MEMBER_HOLONYM"  // X is a member of Y
	RelationPartHolonym    = "PART_HOLONYM"    // X is a part of Y
	RelationMemberMeronym  = "MEMBER_MERONYM"  // Y has member X
	RelationPartMeronym    = "PART_MERONYM"    // Y has part X
	RelationAttribute      = "ATTRIBUTE"       // attribute relation
	RelationSimilar        = "SIMILAR"         // similar to
	RelationParticipleOf   = "PARTICIPLE_OF"   // verb participle form
	RelationDerivedFrom    = "DERIVED_FROM"    // derived/related form
	RelationCategory       = "CATEGORY"        // domain category
	RelationCategoryMember = "CATEGORY_MEMBER" // member of domain category
)

RelationType constants for semantic relations between lexemes.

Variables

View Source 
var (
	ErrInvalidInput             = errors.New("invalid input")
	ErrUserNotFound             = errors.New("user not found")
	ErrInvalidUserName          = errors.New("invalid user name")
	ErrInvalidUserEmail         = errors.New("invalid user email")
	ErrUserAlreadyExists        = errors.New("user already exists")
	ErrInvalidUserID            = errors.New("invalid user ID")
	ErrLearnedLexemeNotFound    = errors.New("user lexeme not found")
	ErrDuplicateLearnedLexeme   = errors.New("user lexeme already exists")
	ErrInvalidLearnedLexemeText = errors.New("invalid user lexeme text")
	ErrLearnedWordNotFound      = errors.New("user word not found")
	ErrDuplicateLearnedWord     = errors.New("user word already exists")
	ErrInvalidLearnedWordText   = errors.New("invalid user word text")
	ErrLexemeRequired           = errors.New("lexeme id is required")
	ErrLexemeNotFound           = errors.New("lexeme not found")
	ErrLanguageMismatch         = errors.New("language mismatch")
	ErrInvalidLexemeID          = errors.New("invalid lexeme id")
	ErrInvalidLexemeText        = errors.New("invalid lexeme text")
	ErrDuplicateLexeme          = errors.New("lexeme already exists")
	ErrWordNotFound             = errors.New("word not found")
	ErrInvalidWordID            = errors.New("invalid word id")
	ErrDuplicateWord            = errors.New("word already exists")

	ErrWordbookNotFound      = errors.New("wordbook not found")
	ErrInvalidWordbookID     = errors.New("invalid wordbook id")
	ErrInvalidWordbookName   = errors.New("invalid wordbook name")
	ErrInvalidWordbookUser   = errors.New("invalid wordbook owner")
	ErrBuiltinWordbookLocked = errors.New("builtin wordbook is read-only")
	ErrDuplicateWordbook     = errors.New("wordbook already exists")

	ErrReviewPlanNotFound    = errors.New("review plan not found")
	ErrInvalidReviewPlanID   = errors.New("invalid review plan id")
	ErrInvalidReviewPlanName = errors.New("invalid review plan name")
	ErrDuplicateReviewPlan   = errors.New("review plan already exists")

	ErrPipelineJobNotFound = errors.New("pipeline job not found")
)

Domain errors for user entity and related aggregates.

Functions

func EndOfDay added in v0.4.0 

func EndOfDay(t time.Time) time.Time

EndOfDay returns the end-of-day timestamp (inclusive) for the given time.

func IsReviewDue added in v0.4.0 

func IsReviewDue(next time.Time, cutoff time.Time) bool

IsReviewDue reports whether the next review time is scheduled and due by the cutoff.

func IsValidPartOfSpeech added in v0.8.0 

func IsValidPartOfSpeech(pos PartOfSpeech) bool

IsValidPartOfSpeech reports whether pos is one of the canonical enum values.

func NormalizeDate added in v0.4.0 

func NormalizeDate(t time.Time) time.Time

NormalizeDate converts a timestamp to a date identifier stored as UTC midnight. It extracts the date in the input's timezone, then returns that date at UTC midnight.

Example: 

Input:  2025-12-08 20:30:00 CST (UTC+8)
Output: 2025-12-08 00:00:00 UTC

This ensures: - Database always stores UTC midnight (consistent format) - Date represents user's local calendar day - Works correctly with timezone changes (travel)

func StartOfDay added in v0.4.0 

func StartOfDay(t time.Time) time.Time

StartOfDay returns the beginning of the user's day in the same location.

Types

type ActivityCalendarData added in v0.4.0 

type ActivityCalendarData struct {
	Activities []DailyActivityData
}

ActivityCalendarData holds the activity heatmap data.

type AnswerConfig added in v0.4.0 

type AnswerConfig struct {
	IgnoreCase bool
}

AnswerConfig contains validation configuration.

type AnswerResult added in v0.4.0 

type AnswerResult struct {
	LWordID          int64
	CardType         CardType
	Correct          bool
	Accuracy         float32
	TimeSpentSeconds int32
	AnsweredAt       time.Time
}

AnswerResult represents the result of answering a flashcard.

type CardAnswer added in v0.4.0 

type CardAnswer struct {
	CorrectValues []string
	Config        *AnswerConfig
}

CardAnswer represents the correct answer and validation rules.

type CardItem added in v0.4.0 

type CardItem struct {
	ID    string
	Text  string
	Hint  string
	Group string // For matching questions
}

CardItem represents an option or interactive item in a flashcard.

type CardQuestion added in v0.4.0 

type CardQuestion struct {
	Text      string
	AutoPlay  bool
	Phonetics []Phonetic
	ImageURL  string
}

CardQuestion represents the question content of a flashcard.

type CardType added in v0.4.0 

type CardType string

CardType represents the type of flashcard. 

const (
	CardTypeCHOICE       CardType = "CHOICE"
	CardTypeSPELLING     CardType = "SPELLING"
	CardTypeSELECT_WORDS CardType = "SELECT_WORDS"
)

type CategoryStat added in v0.3.0 

type CategoryStat struct {
	Category string
	Count    int64
}

CategoryStat summarizes how many lemmas fall under a specific category label.

type CompletenessBucket added in v0.3.0 

type CompletenessBucket struct {
	Label string
	Min   int32
	Max   int32
	Count int64
}

CompletenessBucket is a histogram bucket describing how many words fall within a specific completeness score range.

type DailyActivityData added in v0.4.0 

type DailyActivityData struct {
	Date  string // "YYYY-MM-DD"
	Count int32  // Total activity count
	Level int32  // Activity level 0-4 (for heatmap color intensity)
}

DailyActivityData represents a single day's activity.

type DailyStats added in v0.4.0 

type DailyStats struct {
	ID               int64
	UserID           uuid.UUID
	PlanID           int64
	Date             time.Time // User's local date stored as UTC midnight (YYYY-MM-DD 00:00:00 UTC)
	CardsReviewed    int32
	NewWords         int32
	TimeSpentSeconds int32
	AverageScore     float32 // 0.0-1.0
	WordsMastered    int32
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

DailyStats represents daily learning statistics for a user per review plan.

type DailyTaskStats added in v0.4.0 

type DailyTaskStats struct {
	ReviewDue          int32
	NewWordsRemaining  int32
	NewWordsCompleted  int32
	CardsReviewedToday int32
}

type DashboardStats added in v0.4.0 

type DashboardStats struct {
	// Global Progress
	TotalWords    int32
	MasteredWords int32

	// Today Overview
	TodayReviewedCount int32
	TodayDueWords      int32
	TodayNewWords      int32
	TodayTimeSpent     int32 // seconds

	// Motivation
	StreakDays int32
}

DashboardStats represents the dashboard overview metrics.

type DistillCache added in v0.8.0 

type DistillCache struct {
	ID            int64
	ContextHash   string // SHA256(Context + Prompt + Model)
	Model         string
	PromptSummary string
	Response      map[string]any
	TokenCount    int32
	CreatedAt     time.Time
}

DistillCache stores cached LLM distillation responses.

type FlashCard added in v0.4.0 

type FlashCard struct {
	ID          string
	Type        CardType
	LWordID     int64
	Prompt      string
	Question    *CardQuestion
	Options     []*CardItem
	Answer      *CardAnswer
	Difficulty  int32
	Annotations map[string]string
}

FlashCard represents a single flashcard for vocabulary review.

type FlashCardSet added in v0.4.0 

type FlashCardSet struct {
	Cards []*FlashCard
	Stats *FlashCardStats
}

FlashCardSet represents a collection of flashcards with statistics.

type FlashCardStats added in v0.4.0 

type FlashCardStats struct {
	// Today's total tasks (fixed values for progress calculation)
	TodayDueTotal int32 // Total number of words due at start of day
	TodayNewTotal int32 // Daily new words quota

	// Remaining tasks (dynamic values)
	TodayDueRemaining  int32 // Remaining words due for review
	TodayNewRemaining  int32 // Remaining new words quota
	TodayReviewedCount int32 // Number of cards already reviewed today

	// Other
	EstimatedMinutes int32 // Estimated time to complete current batch (minutes)
}

FlashCardStats contains statistics about the flashcard set.

type Frequency added in v0.7.0 

type Frequency struct {
	Corpus string `json:"corpus"`
	Count  int64  `json:"count"`
}

type InventoryStats added in v0.4.0 

type InventoryStats struct {
	TotalWords    int32
	UnknownWords  int32
	LearningWords int32
	MasteredWords int32
}

type JobAction added in v0.8.0 

type JobAction string

JobAction represents an action to perform on a job. 

const (
	JobActionPause  JobAction = "pause"
	JobActionResume JobAction = "resume"
	JobActionCancel JobAction = "cancel"
	JobActionRetry  JobAction = "retry"
)

func (JobAction) TargetStatus added in v0.8.0 

func (action JobAction) TargetStatus() JobStatus

TargetStatus returns the target status for a given action.

type JobStatus added in v0.8.0 

type JobStatus string

JobStatus represents the state of a pipeline job. 

const (
	JobStatusPending   JobStatus = "PENDING"
	JobStatusRunning   JobStatus = "RUNNING"
	JobStatusPaused    JobStatus = "PAUSED"
	JobStatusCompleted JobStatus = "COMPLETED"
	JobStatusFailed    JobStatus = "FAILED"
	JobStatusCancelled JobStatus = "CANCELLED"
)

func (JobStatus) IsTerminal added in v0.8.0 

func (s JobStatus) IsTerminal() bool

IsTerminal returns true if the job status is a terminal state.

func (JobStatus) ValidateTransition added in v0.8.0 

func (s JobStatus) ValidateTransition(action JobAction) error

ValidateTransition checks if the action can be performed on the current status.

type Language 

type Language string

Language represents supported language codes using ISO-style abbreviations. 

const (
	LanguageUnspecified Language = ""
	LanguageEnglish     Language = "en"
	LanguageChinese     Language = "zh"
	LanguageSpanish     Language = "es"
	LanguageFrench      Language = "fr"
	LanguageGerman      Language = "de"
	LanguageJapanese    Language = "ja"
	LanguageKorean      Language = "ko"
)

func NormalizeLanguage 

func NormalizeLanguage(lang Language) Language

NormalizeLanguage ensures the language falls back to a supported value (defaults to English).

func ParseLanguage 

func ParseLanguage(code string) Language

ParseLanguage converts an arbitrary string into a supported Language value.

func (Language) Code 

func (l Language) Code() string

Code returns the lowercase language code (without defaulting).

func (Language) CodeOrDefault 

func (l Language) CodeOrDefault() string

CodeOrDefault returns the language code, falling back to English when unspecified.

type LearnedWord added in v0.3.0 

type LearnedWord struct {
	ID           int64
	UserID       uuid.UUID
	LexemeID     string
	Term         string // The term stored: lemma for regular forms, or the term itself for irregular forms
	Normal       string // Normalized lowercase form of term for case-insensitive querying
	Language     Language
	Tags         []string
	Notes        []string
	Relations    []LearnedWordRelation
	Contexts     []LearnedWordContext // Context sentences where user encountered this word
	Mastery      MasteryBreakdown
	Review       ReviewTiming
	QueriedCount int64
	CreatedAt    time.Time
	UpdatedAt    time.Time

	MatchedTerms []string // All query terms that matched this stored term

}

LearnedWord represents a user's personalised vocabulary entry. This is a word-level learning record (not lexeme-level), which simplifies the user experience for the majority of cases where multi-sense tracking is not needed.

func (*LearnedWord) Normalize added in v0.3.0 

func (uw *LearnedWord) Normalize(now time.Time)

Normalize ensures defaults & constraints before persistence.

type LearnedWordContext added in v0.3.0 

type LearnedWordContext struct {
	Sentence    string    `json:"sentence"`     // The sentence containing the word
	Source      int32     `json:"source"`       // How this context was added (article, book, manual, etc.)
	SourceRef   string    `json:"source_ref"`   // Optional reference (article title, book name, URL, etc.)
	CollectedAt time.Time `json:"collected_at"` // When this context was collected
}

LearnedWordContext stores a sentence/context where user encountered the word.

type LearnedWordRelation added in v0.3.0 

type LearnedWordRelation struct {
	Word         string    `json:"word"`
	RelationType int32     `json:"relation_type"`
	Note         string    `json:"note,omitempty"`
	CreatedBy    string    `json:"created_by"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
}

LearnedWordRelation links a user word to another concept in their vocabulary graph.

type Lemma added in v0.3.0 

type Lemma struct {
	ID          int64
	Surface     string
	Normalized  string
	Variant     string
	Level       string
	Frequencies []Frequency
	Syllables   []string
	Forms       []*LemmaForm

	CreatedAt time.Time
	UpdatedAt time.Time
}

Lemma represents the canonical form of a word, along with its associated lexemes.

type LemmaForm added in v0.7.0 

type LemmaForm struct {
	ID          int64
	LemmaID     int64
	Surface     string
	Normalized  string
	FormType    LexemeFormType
	IsIrregular bool
	Phonetics   []Phonetic
	Syllables   []string

	CreatedAt time.Time
	UpdatedAt time.Time
}

LexemeForm captures a surfaced variant of a lexeme's lemma.

type LemmaSnapshot added in v0.8.0 

type LemmaSnapshot struct {
	ID            int64
	LemmaID       int64
	JobID         *int64
	Surface       string
	Normalized    string
	LookupTerms   []string
	Language      string
	IsLatest      bool
	Version       int32
	SchemaVersion int32
	Payload       LemmaSnapshotData
	Quality       QualityScore
	LexemeCount   int32
	SenseCount    int32
	FormCount     int32
	RelationCount int32
	ProviderCount int32
	SynthesizedAt time.Time
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

LemmaSnapshot is the materialized, self-contained view of a lemma's knowledge.

type LemmaSnapshotData added in v0.8.0 

type LemmaSnapshotData struct {
	Lexemes     []LemmaSnapshotLexeme   `json:"lexemes,omitempty"`
	Forms       []LemmaSnapshotForm     `json:"forms,omitempty"`
	Categories  []string                `json:"categories,omitempty"`
	Frequencies []Frequency             `json:"frequencies,omitempty"`
	Relations   []LemmaSnapshotRelation `json:"relations,omitempty"`
}

LemmaSnapshotData is the self-contained materialized snapshot payload stored as JSON.

type LemmaSnapshotForm added in v0.8.0 

type LemmaSnapshotForm struct {
	Surface     string     `json:"surface"`
	FormType    string     `json:"form_type"`
	IsIrregular bool       `json:"is_irregular,omitempty"`
	Phonetics   []Phonetic `json:"phonetics,omitempty"`
}

LemmaSnapshotForm represents an inflected form within a snapshot.

type LemmaSnapshotLexeme added in v0.8.0 

type LemmaSnapshotLexeme struct {
	ExternalID string               `json:"external_id,omitempty"`
	Language   string               `json:"language,omitempty"`
	POS        string               `json:"pos"`
	Senses     []LemmaSnapshotSense `json:"senses,omitempty"`
}

LemmaSnapshotLexeme represents a POS-grouped lexeme entry within a snapshot.

type LemmaSnapshotRelation added in v0.8.0 

type LemmaSnapshotRelation struct {
	RelationType   string  `json:"relation_type"`
	TargetTerm     string  `json:"target_term"`
	TargetRef      string  `json:"target_ref,omitempty"`
	Provider       string  `json:"provider"`
	Strength       float64 `json:"strength"`
	SenseMapped    bool    `json:"sense_mapped,omitempty"`
	TargetResolved bool    `json:"target_resolved,omitempty"`
}

LemmaSnapshotRelation represents a semantic relation within a snapshot.

type LemmaSnapshotSense added in v0.8.0 

type LemmaSnapshotSense struct {
	Language    string   `json:"language"`
	Gloss       string   `json:"gloss"`
	Examples    []string `json:"examples,omitempty"`
	Provider    string   `json:"provider,omitempty"`
	TrustWeight float64  `json:"trust_weight,omitempty"`
}

LemmaSnapshotSense represents a single definition/gloss within a snapshot.

type Lexeme added in v0.3.0 

type Lexeme struct {
	ID           int64
	LemmaID      int64  // Foreign key to Lemma
	ExternalID   string // Wikidata Lexeme ID (e.g. "L123456")
	Language     Language
	PartOfSpeech PartOfSpeech
	EntryType    LexemeEntryType
	SenseGloss   string
	Senses       []LexemeSense
	Categories   []string
	Completeness int32

	CreatedAt time.Time
	UpdatedAt time.Time
}

Lexeme captures a semantic entry with its forms, senses, and metadata.

type LexemeEntryType added in v0.3.0 

type LexemeEntryType string

LexemeEntryType distinguishes between top-level entry categories. 

const (
	LexemeEntryTypeUnspecified LexemeEntryType = ""
	LexemeEntryTypeWord        LexemeEntryType = "WORD"
	LexemeEntryTypePhrase      LexemeEntryType = "PHRASE"
	LexemeEntryTypeIdiom       LexemeEntryType = "IDIOM"
)

type LexemeFormType added in v0.3.0 

type LexemeFormType string

LexemeFormType enumerates normalized surface-form categories. 

const (
	LexemeFormTypeUnspecified         LexemeFormType = ""
	LexemeFormTypeLemma               LexemeFormType = "LEMMA"
	LexemeFormTypePlural              LexemeFormType = "PLURAL"
	LexemeFormTypePast                LexemeFormType = "PAST"
	LexemeFormTypePastParticiple      LexemeFormType = "PAST_PARTICIPLE"
	LexemeFormTypePresentParticiple   LexemeFormType = "PRESENT_PARTICIPLE"
	LexemeFormTypeThirdPersonSingular LexemeFormType = "THIRD_PERSON_SINGULAR"
	LexemeFormTypeComparative         LexemeFormType = "COMPARATIVE"
	LexemeFormTypeSuperlative         LexemeFormType = "SUPERLATIVE"
	LexemeFormTypeImperative          LexemeFormType = "IMPERATIVE"
	LexemeFormTypeSubjunctive         LexemeFormType = "SUBJUNCTIVE"
	LexemeFormTypeGerund              LexemeFormType = "GERUND"
	LexemeFormTypeShortForm           LexemeFormType = "SHORT_FORM"
)

type LexemeSense added in v0.3.0 

type LexemeSense struct {
	Language Language       `json:"language"`
	Gloss    string         `json:"gloss"`
	Examples []SenseExample `json:"examples,omitempty"`
}

LexemeSense models a language-specific gloss for a particular part of speech.

type MasteryBreakdown 

type MasteryBreakdown struct {
	Listen    int32
	Read      int32
	Spell     int32
	Pronounce int32
	Overall   int32
}

MasteryBreakdown captures skill-specific mastery scores for a user word.

func (MasteryBreakdown) CalculateMasteryLevel added in v0.5.0 

func (m MasteryBreakdown) CalculateMasteryLevel() MasteryLevel

CalculateMasteryLevel determines the mastery level based on the overall score. Returns one of: UNSPECIFIED, UNKNOWN, RECOGNIZED, UNDERSTOOD, PROFICIENT, or MASTERED.

Thresholds are midpoints between adjacent InitializeFromUserMasteryLevel values: 

overall == 0         → UNSPECIFIED
overall < 126        → UNKNOWN     (Level 1 init produces ~90)
overall 126-219      → RECOGNIZED  (Level 2 init produces ~162)
overall 220-312      → UNDERSTOOD  (Level 3 init produces ~278)
overall 313-417      → PROFICIENT  (Level 4 init produces ~348)
overall >= 418       → MASTERED    (Level 5 init produces ~488)

func (MasteryBreakdown) CalculateOverall added in v0.5.0 

func (m MasteryBreakdown) CalculateOverall() int32

CalculateOverall computes the overall mastery score using weighted formula. Returns 0-500 (representing 0.0-5.0 with centpoints). Formula:

  • Receptive (passive) = (Read + Listen) / 2.0
  • Productive (active) = 0.3 * Spell + 0.7 * Pronounce (speaking weighted higher)
  • Overall = round((0.6 * Receptive + 0.4 * Productive) * 100)

func (*MasteryBreakdown) InitializeFromUserMasteryLevel added in v0.5.0 

func (m *MasteryBreakdown) InitializeFromUserMasteryLevel(level int32)

InitializeFromUserMasteryLevel converts user's mastery level (1-5) into four-dimensional breakdown based on typical language learning progression. Level 0 means unspecified (user hasn't set a level).

Conversion rationale:

  • Receptive skills (read/listen) develop before productive skills (spell/speak)
  • Reading is typically easier than listening (visual vs auditory input)
  • Speaking is easier than spelling (phonetic vs orthographic accuracy)
  • Conservative production estimates avoid over-estimating active skills

func (*MasteryBreakdown) Normalize added in v0.5.0 

func (m *MasteryBreakdown) Normalize()

Normalize ensures overall is calculated from dimensions.

type MasteryDistributionData added in v0.4.0 

type MasteryDistributionData struct {
	Distribution map[int32]int32 // key: mastery level (0-5), value: count
	GeneratedAt  time.Time
}

MasteryDistributionData holds the distribution of words by mastery level.

type MasteryLevel added in v0.5.0 

type MasteryLevel int32

MasteryLevel represents the user's current mastery state for a word. 

const (
	MasteryLevelUnspecified MasteryLevel = 0 // Not set (system default)
	MasteryLevelUnknown     MasteryLevel = 1 // Completely unfamiliar
	MasteryLevelRecognized  MasteryLevel = 2 // Seen before, can identify
	MasteryLevelUnderstood  MasteryLevel = 3 // Know the meaning
	MasteryLevelProficient  MasteryLevel = 4 // Can use actively
	MasteryLevelMastered    MasteryLevel = 5 // Fluent, automatic
)

func MasteryLevelFromOverall added in v0.5.4 

func MasteryLevelFromOverall(overall int32) MasteryLevel

MasteryLevelFromOverall converts an overall score (0-500) to a MasteryLevel.

type PartOfSpeech added in v0.8.0 

type PartOfSpeech string

PartOfSpeech is the canonical internal POS enum used across all data sources. Core set = UPOS, plus a small controlled extension set. 

const (
	PartOfSpeechUnspecified  PartOfSpeech = ""
	PartOfSpeechNoun         PartOfSpeech = "noun"
	PartOfSpeechVerb         PartOfSpeech = "verb"
	PartOfSpeechAdjective    PartOfSpeech = "adj"
	PartOfSpeechAdverb       PartOfSpeech = "adv"
	PartOfSpeechPronoun      PartOfSpeech = "pron"
	PartOfSpeechProperNoun   PartOfSpeech = "propn"
	PartOfSpeechAdposition   PartOfSpeech = "adp"
	PartOfSpeechDeterminer   PartOfSpeech = "det"
	PartOfSpeechNumeral      PartOfSpeech = "num"
	PartOfSpeechCCONJ        PartOfSpeech = "cconj"
	PartOfSpeechSCONJ        PartOfSpeech = "sconj"
	PartOfSpeechParticle     PartOfSpeech = "part"
	PartOfSpeechInterjection PartOfSpeech = "intj"
	PartOfSpeechAuxiliary    PartOfSpeech = "aux"
	PartOfSpeechSymbol       PartOfSpeech = "sym"
	PartOfSpeechOther        PartOfSpeech = "x"

	// Controlled extensions over UPOS.
	PartOfSpeechAbbreviation PartOfSpeech = "abbr"
	PartOfSpeechAffix        PartOfSpeech = "affix"
	PartOfSpeechPrefix       PartOfSpeech = "prefix"
	PartOfSpeechSuffix       PartOfSpeech = "suffix"
)

func ParsePartOfSpeech added in v0.8.0 

func ParsePartOfSpeech(raw string) (PartOfSpeech, bool)

ParsePartOfSpeech parses a single POS token into the internal enum.

func (PartOfSpeech) Values added in v0.8.0 

func (PartOfSpeech) Values() []string

Values implements Ent's EnumValues contract for schema GoType.

type Phonetic added in v0.3.0 

type Phonetic struct {
	IPA     string `json:"ipa"`
	Dialect string `json:"dialect,omitempty"`
}

Phonetic stores IPA/dialect pairs for surfaced forms.

type PipelineJob added in v0.8.0 

type PipelineJob struct {
	ID       int64
	Status   JobStatus
	Name     string
	Language string
	Tier     int32

	// Single-word job term.
	Term string

	ErrorMessage string

	StartedAt   *time.Time
	CompletedAt *time.Time
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

PipelineJob represents an async pipeline processing job.

type PipelinePhase added in v0.8.0 

type PipelinePhase int32

PipelinePhase enumerates the five pipeline stages. 

const (
	PhaseDiscovery    PipelinePhase = 1
	PhaseLexical      PipelinePhase = 2
	PhaseRelational   PipelinePhase = 3
	PhaseIntellectual PipelinePhase = 4
	PhaseSynthesis    PipelinePhase = 5
)

func (PipelinePhase) Name added in v0.8.0 

func (p PipelinePhase) Name() string

PhaseName returns a human-readable name for the phase.

type PipelineStage added in v0.8.0 

type PipelineStage struct {
	ID           int64
	JobID        int64
	LemmaID      int64
	Phase        int32
	Status       StageStatus
	Tier         int32 // 1=Core, 2=Extended, 3=LongTail
	Attempts     int32
	ErrorMessage string
	StartedAt    *time.Time
	CompletedAt  *time.Time
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

PipelineStage tracks the execution state of a single pipeline phase for a job.

type QualityScore added in v0.8.0 

type QualityScore struct {
	Overall      float64 `json:"overall"`
	Completeness float64 `json:"completeness"`
	Depth        float64 `json:"depth"`
	Density      float64 `json:"density"`
	Validity     float64 `json:"validity"`
}

QualityScore captures multi-dimensional quality metrics for a lemma snapshot.

type RawEvidence added in v0.8.0 

type RawEvidence struct {
	ID            int64
	LemmaID       int64
	Provider      string // "wikidata", "wordnet", "ecdict", "conceptnet", "llm", "manual"
	Phase         int32  // 1-5
	Content       map[string]any
	SchemaVersion string
	FetchedAt     time.Time
	CreatedAt     time.Time
}

RawEvidence stores a raw response envelope from an external data provider.

type ReviewPlan added in v0.4.0 

type ReviewPlan struct {
	ID          int64
	UserID      uuid.UUID
	Name        string
	Description string
	Config      ReviewPlanConfig
	WordbookIDs []int64
	Status      ReviewPlanStatus
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

ReviewPlan represents a user's vocabulary review plan configuration.

func NormalizeReviewPlan added in v0.4.0 

func NormalizeReviewPlan(in *ReviewPlan) (*ReviewPlan, error)

NormalizeReviewPlan cleans string fields, sets defaults, and ensures invariants.

type ReviewPlanConfig added in v0.4.0 

type ReviewPlanConfig struct {
	DailyNewLimit int32
}

ReviewPlanConfig holds configuration for a review plan.

type ReviewPlanStatus added in v0.4.0 

type ReviewPlanStatus struct {
	Inventory InventoryStats
	DailyTask DailyTaskStats
	Wordbooks []*Wordbook
}

ReviewPlanStatus contains computed statistics about a review plan.

type ReviewTiming 

type ReviewTiming struct {
	LastReviewAt time.Time
	NextReviewAt time.Time
	IntervalDays int32
	FailCount    int32 // Cumulative failure count (not reset on success) for FSRS
	Reps         int32 // Total number of reviews (repetitions) for FSRS
}

ReviewTiming represents spaced repetition metadata for a user lexeme.

type SemanticRelation added in v0.8.0 

type SemanticRelation struct {
	ID               int64
	SourceLexemeID   int64  // DB foreign key, set by persistence layer
	SourceExternalID string // Wikidata ExternalID, set by processors
	TargetLexemeID   *int64 // nil = unresolved
	TargetRef        string // stable target URI, e.g. wikidata://lexeme/L123
	TargetTerm       string // always set, display text
	RelationType     string
	Provider         string  // "wordnet", "conceptnet", "ecdict", "llm", "manual"
	Strength         float64 // 0.0-1.0
	SenseMapped      bool
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

SemanticRelation links two lexemes with a typed semantic relationship.

type SenseExample added in v0.3.0 

type SenseExample struct {
	Text        string `json:"text"`
	Translation string `json:"translation,omitempty"`
}

SenseExample illustrates a particular sense.

type StageProgressSummary added in v0.8.0 

type StageProgressSummary struct {
	Total     int
	Completed int
	Failed    int
	Skipped   int
	Running   int
	Pending   int
}

StageProgressSummary aggregates stage statuses for display.

func ComputeStageProgress added in v0.8.0 

func ComputeStageProgress(stages []*PipelineStage) *StageProgressSummary

ComputeStageProgress computes a StageProgressSummary from a list of stages.

func (*StageProgressSummary) String added in v0.8.0 

func (s *StageProgressSummary) String() string

String returns a compact representation, e.g. "5/5" or "3/5 (skip:1, fail:1)".

type StageStatus added in v0.8.0 

type StageStatus string

StageStatus represents the state of a pipeline stage. 

const (
	StageStatusPending   StageStatus = "PENDING"
	StageStatusRunning   StageStatus = "RUNNING"
	StageStatusCompleted StageStatus = "COMPLETED"
	StageStatusFailed    StageStatus = "FAILED"
	StageStatusSkipped   StageStatus = "SKIPPED"
)

type WordCoverage added in v0.3.0 

type WordCoverage struct {
	Phonetics   float64
	Categories  float64
	Definitions float64
	Forms       float64
}

WordCoverage captures the percentage of words that carry a specific attribute.

type WordEntry added in v0.3.0 

type WordEntry struct {
	QueriedTerm string
	Lemma       *Lemma   // The lemma that was found (contains forms and lexeme reference)
	Lexemies    []Lexeme // Associated lexemes with semantic information
}

WordEntry carries lookup context for a lemma and the queried surface term.

type WordLanguageStats added in v0.3.0 

type WordLanguageStats struct {
	Language           Language
	WordCount          int64
	LexemeCount        int64
	AvgCompleteness    float64
	PhoneticCoverage   float64
	DefinitionCoverage float64
	FormCoverage       float64
	CategoryCoverage   float64
}

WordLanguageStats exposes per-language richness and completeness data.

type WordStats added in v0.3.0 

type WordStats struct {
	Summary       WordStatsSummary
	Coverage      WordCoverage
	Languages     []WordLanguageStats
	TopCategories []CategoryStat
	Completeness  []CompletenessBucket
}

WordStats bundles the aggregated data needed for the overview dashboard.

type WordStatsFilter added in v0.3.0 

type WordStatsFilter struct {
	Languages []Language
}

WordStatsFilter scopes statistics to specific languages.

type WordStatsSummary added in v0.3.0 

type WordStatsSummary struct {
	TotalWords      int64
	TotalLexemes    int64
	TotalForms      int64
	AvgCompleteness float64
	NewLast24h      int64
	NewLast7d       int64
}

WordStatsSummary surfaces top-line metrics such as totals and recent growth.

type Wordbook added in v0.4.0 

type Wordbook struct {
	ID          int64
	UserID      uuid.UUID
	Source      WordbookSource
	Language    Language
	Visibility  WordbookVisibility
	Name        string
	Description string
	Annotations map[string]string
	Terms       []string
	Stats       WordbookStats
	SortOrder   int32
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Wordbook aggregates vocabulary terms into a named collection.

func NormalizeWordbook added in v0.4.0 

func NormalizeWordbook(in *Wordbook) (*Wordbook, error)

NormalizeWordbook cleans string fields, sets defaults, and ensures invariants.

type WordbookSource added in v0.4.0 

type WordbookSource string

WordbookSource marks where the wordbook comes from. 

const (
	WordbookSourceBuiltin WordbookSource = "builtin"
	WordbookSourceUser    WordbookSource = "user"
)

type WordbookStats added in v0.4.0 

type WordbookStats struct {
	TotalWords    int32
	MasteredWords int32 // overall >= 418
	LearningWords int32 // overall 126-417
	UnknownWords  int32 // overall < 126
	ReviewDue     int32
}

WordbookStats stores learning progress counters. Thresholds are based on overall score (0-500 scale):

  • MasteredWords: overall >= 418 (Level 5)
  • LearningWords: overall 126-417 (Level 2-4)
  • UnknownWords: overall < 126 (Level 0-1)

type WordbookVisibility added in v0.4.0 

type WordbookVisibility string

WordbookVisibility aligns with proto visibility values. 

const (
	WordbookVisibilityUnspecified WordbookVisibility = ""
	WordbookVisibilityPrivate     WordbookVisibility = "private"
	WordbookVisibilityPublic      WordbookVisibility = "public"
	WordbookVisibilityShared      WordbookVisibility = "shared"
)

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.