qmd

package
v0.0.11 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package qmd provides a shell-backed client for the QMD CLI.

Index

Constants

View Source 
const (
	// DefaultBinaryPath is the default executable name used to locate QMD.
	DefaultBinaryPath = "qmd"
	// InstallCommand is the recommended install command for the QMD CLI.
	InstallCommand = "npm install -g @tobilu/qmd"
	// CollectionMask is the `--mask` of every collection kb creates: all
	// markdown except quarantined sources (`raw/_quarantine/`, spec §7) and
	// decision records (`.decisions/`, which qmd skips as a dot directory
	// anyway). qmd stores it as the collection pattern, so `qmd update`
	// keeps honouring it; its negated globs are passed to fast-glob.
	CollectionMask = "**/*.md,!**/raw/_quarantine/**,!**/.decisions/**"
)

Variables

View Source 
var (
	// ErrQMDUnavailable indicates the QMD CLI could not be found on PATH.
	ErrQMDUnavailable = errors.New("qmd is not available")
)

Functions

func ExcludedPath added in v0.0.11 

func ExcludedPath(p string) bool

ExcludedPath reports whether a qmd hit path (a `qmd://<collection>/...` URI, a collection-relative or an on-disk path) points into a topic's quarantine (`raw/_quarantine/`, spec §7) or its `.decisions/` records. Quarantined files are out of every pipeline, qmd search included. New collections exclude them through CollectionMask; collections created before it may still hold them, so every hit list is also filtered (after over-fetching, see overFetchLimit). Some qmd versions normalize path segments before showing them (`_quarantine` becomes `quarantine`), so both spellings under `raw/` match; `.decisions/` is a dot directory qmd never indexes, matched for indexes built otherwise.

Types

type Candidates added in v0.0.11 

type Candidates struct {
	// contains filtered or unexported fields
}

Candidates proposes topic documents by qmd vector similarity. It implements link.Neighbours and find.Vectors. Use OpenCandidates, which only returns one when the topic collection exists and is fresh.

func (*Candidates) Neighbours added in v0.0.11 

func (c *Candidates) Neighbours(ctx context.Context, doc *corpus.Document, k int) ([]string, error)

Neighbours implements link.Neighbours: the top k wiki articles closest to the document's title, summary and opening text, the document itself and non-article paths excluded.

func (*Candidates) Query added in v0.0.11 

func (c *Candidates) Query(ctx context.Context, text string, limit int) ([]string, error)

Query runs one no-rerank vector query and returns up to limit collection-relative paths, best first, without duplicates. It over-fetches (fetchEligible) so quarantined hits of an older collection cannot use up the window before filtering.

func (*Candidates) Search added in v0.0.11 

func (c *Candidates) Search(ctx context.Context, query string, k int) ([]string, error)

Search implements find.Vectors: the top k topic documents closest to the question.

type ClientOption 

type ClientOption func(*QMDClient)

ClientOption mutates a QMDClient configuration.

func WithBinaryPath 

func WithBinaryPath(path string) ClientOption

WithBinaryPath overrides the executable used for QMD invocations.

func WithIndexName 

func WithIndexName(name string) ClientOption

WithIndexName routes QMD commands to a named SQLite index.

type CollectionInfo 

type CollectionInfo struct {
	Name        string `json:"name"`
	Path        string `json:"path"`
	Pattern     string `json:"pattern"`
	Documents   int    `json:"documents"`
	LastUpdated string `json:"lastUpdated"`
}

CollectionInfo summarizes one indexed QMD collection.

type EmbedResult 

type EmbedResult struct {
	DocsProcessed  int `json:"docsProcessed"`
	ChunksEmbedded int `json:"chunksEmbedded"`
	Errors         int `json:"errors"`
	DurationMs     int `json:"durationMs"`
}

EmbedResult mirrors QMD's embedding summary.

type EmbedStatus added in v0.0.4 

type EmbedStatus string

EmbedStatus summarizes the outcome of the optional embedding phase. 

const (
	// EmbedStatusNotRequested means the caller disabled embeddings.
	EmbedStatusNotRequested EmbedStatus = "not_requested"
	// EmbedStatusCompleted means embeddings ran successfully.
	EmbedStatusCompleted EmbedStatus = "completed"
	// EmbedStatusSkippedUnavailable means embeddings were skipped because the
	// runtime lacks sqlite-vec support.
	EmbedStatusSkippedUnavailable EmbedStatus = "skipped_unavailable"
)

type IndexOperation 

type IndexOperation string

IndexOperation selects whether Index creates a collection or updates one. 

const (
	// IndexOperationAdd creates a collection and performs the initial sync.
	IndexOperationAdd IndexOperation = "add"
	// IndexOperationUpdate refreshes an existing collection.
	IndexOperationUpdate IndexOperation = "update"
)

type IndexOptions 

type IndexOptions struct {
	Operation      IndexOperation
	VaultPath      string
	CollectionName string
	Context        string
	Embed          bool
	ForceEmbed     bool
}

IndexOptions configures a collection sync invocation.

type IndexResult 

type IndexResult struct {
	CollectionName string       `json:"collectionName"`
	UpdateResult   UpdateResult `json:"updateResult"`
	EmbedResult    *EmbedResult `json:"embedResult,omitempty"`
	EmbedStatus    EmbedStatus  `json:"embedStatus"`
	EmbedWarning   string       `json:"embedWarning,omitempty"`
	Status         IndexStatus  `json:"status"`
}

IndexResult groups the collection sync summary, optional embedding summary, and the final index status snapshot.

type IndexStatus 

type IndexStatus struct {
	TotalDocuments int              `json:"totalDocuments"`
	NeedsEmbedding int              `json:"needsEmbedding"`
	HasVectorIndex bool             `json:"hasVectorIndex"`
	Collections    []CollectionInfo `json:"collections"`
}

IndexStatus mirrors QMD's status view for collection health.

type QMDClient 

type QMDClient struct {
	// contains filtered or unexported fields
}

QMDClient executes QMD shell commands with context-aware process management.

func NewClient 

func NewClient(options ...ClientOption) *QMDClient

NewClient constructs a QMDClient with sensible defaults.

func (*QMDClient) Index 

func (client *QMDClient) Index(ctx context.Context, options IndexOptions) (IndexResult, error)

Index creates or updates a QMD collection and returns the structured summary.

func (*QMDClient) OpenCandidates added in v0.0.11 

func (client *QMDClient) OpenCandidates(ctx context.Context, collection, topicRoot string) (*Candidates, string)

OpenCandidates returns vector candidates over the qmd collection of a topic when they can be trusted, or nil and a one-line note saying why they are off. The collection is fresh when:

  • the qmd binary resolves on PATH;
  • `qmd status` lists a collection named collection;
  • the index file reported by `qmd status` (`Index: <path>`) was modified no earlier than the newest `*.md` file of the topic (dot directories skipped), i.e. no topic file changed after the last `kb index`.

The index mtime is index-wide (updating another collection also bumps it), so the rule catches edits made after the last index run, not every stale case; pending embeddings only shrink the vector result set.

func (*QMDClient) Search 

func (client *QMDClient) Search(ctx context.Context, options SearchOptions) ([]SearchResult, error)

Search executes a QMD search command and returns normalized results.

func (*QMDClient) Status 

func (client *QMDClient) Status(ctx context.Context) (IndexStatus, error)

Status returns the current QMD index status summary.

type SearchMode 

type SearchMode string

SearchMode selects the QMD retrieval mode for Search. 

const (
	// SearchModeHybrid runs QMD's hybrid `query` command.
	SearchModeHybrid SearchMode = "hybrid"
	// SearchModeLexical runs QMD's lexical `search` command.
	SearchModeLexical SearchMode = "lexical"
	// SearchModeVector runs QMD's semantic `vsearch` command.
	SearchModeVector SearchMode = "vector"
)

type SearchOptions 

type SearchOptions struct {
	Query      string
	Mode       SearchMode
	Limit      int
	All        bool
	MinScore   *float64
	Full       bool
	Collection string
}

SearchOptions configures a QMD search invocation.

type SearchResult 

type SearchResult struct {
	DocID   string  `json:"docid,omitempty"`
	Path    string  `json:"path"`
	Title   string  `json:"title"`
	Snippet string  `json:"snippet"`
	Score   float64 `json:"score"`
}

SearchResult is the normalized Go representation of a QMD search hit.

type UpdateResult 

type UpdateResult struct {
	Collections    int `json:"collections"`
	Indexed        int `json:"indexed"`
	Updated        int `json:"updated"`
	Unchanged      int `json:"unchanged"`
	Removed        int `json:"removed"`
	NeedsEmbedding int `json:"needsEmbedding"`
}

UpdateResult mirrors QMD's store update summary.

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.