Documentation
¶
Overview ¶
Package failureknowledge holds the offline failure resolution snapshot: a versioned SQLite FTS5 database of promoted failure resolutions that ships with StackKits releases, and its lookup.
A resolution names normalized failure signatures (fk-normalizer), where it applies, the root cause and fix steps as references to StackKits or Techstack procedures. The snapshot holds no installation, tenant or subject data; it is knowledge, never execution authority. A fix runs only through the referenced product procedure.
The snapshot is built from a resolution catalog (schema kombify.failure-resolution-catalog/v1) exported from the curated catalog. Lookup runs offline: exact signature first, then FTS5 lexical search, and a semantic step only when a local Ollama with bge-m3 is configured, against the BGE-M3 vectors the snapshot carries.
Index ¶
Constants ¶
const ( // CatalogSchema is the catalog format the snapshot is built from. CatalogSchema = "kombify.failure-resolution-catalog/v1" // SnapshotSchema versions the SQLite layout. SnapshotSchema = "stackkits.failure-snapshot/v1" // SnapshotFileName is the snapshot's name in release archives and beside // an installed CLI. SnapshotFileName = "failure-resolutions.sqlite" // SnapshotEnv overrides where the CLI finds the snapshot. SnapshotEnv = "STACKKIT_FAILURE_SNAPSHOT" // VectorDimensions is the BGE-M3 dense dimension. VectorDimensions = 1024 )
const ( // OllamaURLEnv names a local Ollama that serves bge-m3; without it the // semantic step does not run. OllamaURLEnv = "STACKKIT_FAILURE_OLLAMA_URL" )
Variables ¶
This section is empty.
Functions ¶
func DefaultSnapshotPath ¶
DefaultSnapshotPath finds the snapshot: STACKKIT_FAILURE_SNAPSHOT, else beside the executable, in its bin directory or in ../lib/stackkit, where release archives and installers place it.
Types ¶
type Applicability ¶
type Applicability struct {
StackKitModules []string `json:"stackkitModules,omitempty"`
StackKitVersions []string `json:"stackkitVersions,omitempty"`
AppVersions []string `json:"appVersions,omitempty"`
OS []string `json:"os,omitempty"`
OSVersions []string `json:"osVersions,omitempty"`
Arch []string `json:"arch,omitempty"`
ContainerRuntimes []string `json:"containerRuntimes,omitempty"`
Providers []string `json:"providers,omitempty"`
DeviceClasses []string `json:"deviceClasses,omitempty"`
}
Applicability lists the contexts a resolution applies to; an empty dimension applies everywhere.
type Catalog ¶
type Catalog struct {
Schema string `json:"schema"`
GeneratedAt time.Time `json:"generatedAt"`
Dimensions int `json:"dimensions"`
VectorEncoding string `json:"vectorEncoding"`
Truncated bool `json:"truncated"`
Resolutions []CatalogRecord `json:"resolutions"`
}
Catalog is the export of promoted resolutions the snapshot is built from.
type CatalogRecord ¶
type CatalogRecord struct {
ID string `json:"id"`
Title string `json:"title"`
Symptoms []Symptom `json:"symptoms"`
Applicability Applicability `json:"applicability"`
RootCause string `json:"rootCause"`
FixSteps []FixStep `json:"fixSteps"`
Evidence Evidence `json:"evidence"`
Revision int `json:"revision"`
ReviewedAt *time.Time `json:"reviewedAt,omitempty"`
SymptomText string `json:"symptomText"`
BodyText string `json:"bodyText"`
EmbeddingModel string `json:"embeddingModel,omitempty"`
Embedding string `json:"embedding,omitempty"`
}
CatalogRecord is one promoted resolution of the catalog.
type Evidence ¶
type Evidence struct {
SuccessCount int `json:"successCount"`
FailureCount int `json:"failureCount"`
SuccessRate float64 `json:"successRate"`
}
Evidence is the verified outcome count of a resolution.
type FixStep ¶
type FixStep struct {
Product string `json:"product"`
Procedure string `json:"procedure"`
Summary string `json:"summary,omitempty"`
}
FixStep references a product procedure; it is never a command.
type Leg ¶
type Leg struct {
Name string `json:"name"`
State string `json:"state"`
Matches int `json:"matches"`
Detail string `json:"detail,omitempty"`
}
Leg reports how one lookup step ran.
type Match ¶
type Match struct {
Rank int `json:"rank"`
Match string `json:"match"`
Score float64 `json:"score"`
Ranks map[string]int `json:"ranks"`
// Similarity is the cosine similarity of the semantic step, when it ran.
Similarity *float64 `json:"similarity,omitempty"`
Resolution Resolution `json:"resolution"`
}
Match is one lookup result.
type Query ¶
type Query struct {
Signature string
Text string
TopK int
// OllamaURL enables the semantic step; empty skips it.
OllamaURL string
}
Query is a normalized failure signature, a free-text description, or both.
type Resolution ¶
type Resolution struct {
ID string `json:"id"`
Title string `json:"title"`
Symptoms []Symptom `json:"symptoms"`
Applicability Applicability `json:"applicability"`
RootCause string `json:"rootCause"`
FixSteps []FixStep `json:"fixSteps"`
Evidence Evidence `json:"evidence"`
Revision int `json:"revision"`
ReviewedAt string `json:"reviewedAt,omitempty"`
}
Resolution is a promoted resolution as the snapshot holds it.
type Result ¶
type Result struct {
Snapshot SnapshotInfo `json:"snapshot"`
Results []Match `json:"results"`
Legs []Leg `json:"legs"`
Advisory bool `json:"advisory"`
}
Result is the lookup answer. A resolution is advisory: a fix runs only through the referenced product procedure.
type Snapshot ¶
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot is an opened, read-only snapshot.
func OpenSnapshot ¶
OpenSnapshot opens a snapshot read-only and checks its schema.
type SnapshotInfo ¶
type SnapshotInfo struct {
Schema string `json:"schema"`
Version string `json:"version"`
CatalogGeneratedAt string `json:"catalogGeneratedAt"`
CatalogSHA256 string `json:"catalogSha256"`
Resolutions int `json:"resolutions"`
Signatures int `json:"signatures"`
Vectors int `json:"vectors"`
EmbeddingModel string `json:"embeddingModel,omitempty"`
Path string `json:"path,omitempty"`
}
SnapshotInfo describes a built or opened snapshot.
func BuildSnapshot ¶
func BuildSnapshot(ctx context.Context, catalog Catalog, catalogSHA256, output string) (SnapshotInfo, error)
BuildSnapshot writes a new snapshot of the catalog to output. The file is written beside output and renamed into place, so a reader never sees a partial snapshot.
type Symptom ¶
type Symptom struct {
Signature string `json:"signature"`
NormalizerVersion string `json:"normalizerVersion,omitempty"`
Component string `json:"component,omitempty"`
Phase string `json:"phase,omitempty"`
ErrorCode string `json:"errorCode,omitempty"`
Template string `json:"template,omitempty"`
}
Symptom is one normalized failure symptom.
Source Files