knowledge

package module
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Jul 28, 2026 License: AGPL-3.0-or-later Imports: 12 Imported by: 0

README

knowledge

A standalone SQLite3-backed knowledge base for tracking projects, observations, and concepts across independent experiments in the rsdoiel/Laboratory workspace. Extracted from the harvey terminal agent's knowledge.go, this module provides a typed CRUD API (Open, AddProject, AddObservationWithSource, AddConceptWithIdentifier, Search, and related methods) plus UUID-based row identity and a SQL/ATTACH-based cross-machine merge tool, so other experiments and language-model harnesses can read and write structured observations directly instead of raw sqlite3 CLI inserts. Ships cmd/kb, a single "kb VERB ARGS" binary (matching the git/go command model) covering the full API with both human-readable and --json output, a merge verb for reconciling two databases that drifted independently, and a read-only interactive TUI browser for exploring projects, observations, and concepts.

Release Notes

  • version: 0.0.1
  • status: concept
  • released: 2026-07-27

Proof-of-concept pre-release. Full CRUD API (projects, observations, concepts, sources) with FTS5 search and cross-machine merge; cmd/kb ships a git/go-style CLI with --json output and a read-mostly bubbletea TUI; --debug emits a JSONL trace of every knowledge-base call and TUI event. Extracted from harvey's knowledge.go/knowledge_merge.go.

Authors
  • Doiel, R. S.

Software Requirements

  • Go >= 1.26.3
Software Suggestions
  • CMTools >= 0.0.45b
  • Pandoc >= 3.9
  • GNU Make >= 3

Documentation

Index

Constants

View Source 
const (
	// Version number of release
	Version = "0.0.2"

	// ReleaseDate, the date version.go was generated
	ReleaseDate = "2026-07-28"

	// ReleaseHash, the Git hash when version.go was generated
	ReleaseHash = "bd1f3d4"
	LicenseText = `` /* 770-byte string literal not displayed */

)
View Source 
const DefaultRetractionWatchURL = "https://api.retractionwatch.com/api/v1/retractiondata/"

DefaultRetractionWatchURL is the base URL for the Retraction Watch API.

Variables

View Source 
var ValidObservationKinds = []string{"note", "finding", "decision", "question", "hypothesis"}

ValidObservationKinds lists the accepted values for Observation.Kind.

Functions

func CheckDOIRetraction 

func CheckDOIRetraction(doi, apiURL string) (retracted bool, note string, err error)

* CheckDOIRetraction queries the Retraction Watch API for the given DOI and

  • reports whether the work has been retracted. *
  • Parameters:
  • doi (string) — DOI to query, e.g. "10.1234/example".
  • apiURL (string) — base URL of the Retraction Watch API; use
  • DefaultRetractionWatchURL for production. *
  • Returns:
  • retracted (bool) — true when the DOI appears in the retraction database.
  • note (string) — human-readable note with reason and date; empty when
  • not retracted.
  • error — on network failure, non-200 response, or bad JSON. *
  • Example:
  • retracted, note, err := CheckDOIRetraction("10.1234/paper", DefaultRetractionWatchURL)
  • if retracted { fmt.Println("retracted:", note) }

func DefaultPath 

func DefaultPath(root string) string

* DefaultPath returns the conventional knowledge.db location under root

  • (root + "agents/knowledge.db"), for callers with no path override of
  • their own. *
  • Parameters:
  • root (string) — the project or workspace root directory. *
  • Returns:
  • string — root joined with "agents/knowledge.db". *
  • Example:
  • dbPath := DefaultPath("/home/user/myproject")
  • kb, err := Open(dbPath)

func FmtHelp 

func FmtHelp(src string, appName string, version string, releaseDate string, releaseHash string) string

FmtHelp lets you process a text block with simple curly brace markup.

func IsValidKind 

func IsValidKind(kind string) bool
  • IsValidKind reports whether kind is one of ValidObservationKinds. *
  • Parameters:
  • kind (string) — the observation kind to check. *
  • Returns:
  • bool — true if kind is a recognized observation kind. *
  • Example:
  • if !knowledge.IsValidKind(kind) {
  • kind = "note"
  • }

func ReconcileCollisions 

func ReconcileCollisions(bPath string, collisions []NameCollision) error

* ReconcileCollisions rewrites, in bPath, the uuid of every row named in

  • collisions to match its counterpart's uuid (UUIDA) — "a" wins. This must
  • be called (and MergeKnowledgeBases must be given the now-rewritten bPath)
  • before merging past a CollisionReport hit: without it, MergeKnowledgeBases
  • resolves a name collision by keeping whichever row it inserts first and
  • silently dropping the other via the uuid/name UNIQUE constraints — which
  • also orphans and drops every child row (observations, links) that pointed
  • at the dropped row through its uuid. Reconciling first means both sides'
  • child rows correctly attach to the single surviving merged parent instead. *
  • Parameters:
  • bPath (string) — path to the knowledge.db whose colliding rows will be rewritten.
  • collisions ([]NameCollision) — the result of CollisionReport(aPath, bPath). *
  • Returns:
  • error — on database failure. *
  • Example:
  • collisions, _ := CollisionReport(aPath, bPath)
  • if len(collisions) > 0 {
  • _ = ReconcileCollisions(bPath, collisions)
  • }
  • summary, _ := MergeKnowledgeBases(aPath, bPath, mergedPath)

Types

type Concept 

type Concept struct {
	ID              int64
	Name            string
	Description     string
	IdentifierType  string
	IdentifierValue string
}

* Concept represents a named idea or term that can be linked to projects and

  • observations. A concept may also represent a scholarly entity — a paper,
  • person, institution, or funder — in which case IdentifierType is one of
  • the IdentifierType values (e.g. "doi", "orcid", "ror", "fundref") and
  • IdentifierValue is that identifier's normalized (extended) form. Both
  • fields are "" for concepts that are plain ideas/terms, not entities. *
  • Example:
  • concepts, err := kb.Concepts()
  • for _, c := range concepts {
  • fmt.Println(c.Name, "-", c.Description)
  • if c.IdentifierType != "" {
  • fmt.Printf(" %s: %s\n", c.IdentifierType, c.IdentifierValue)
  • }
  • }

type KBSearchResult 

type KBSearchResult struct {
	Kind    string
	Label   string
	Snippet string
}
  • KBSearchResult holds one row returned by Search. *
  • Fields:
  • Kind (string) — observation kind ("note", "finding", etc.) or "project" / "concept".
  • Label (string) — project name for observations; entity name for projects and concepts.
  • Snippet (string) — observation body; or description for projects and concepts. *
  • Example:
  • results, _ := kb.Search("WAL mode")
  • for _, r := range results {
  • fmt.Printf("[%s] %s — %s\n", r.Kind, r.Label, r.Snippet)
  • }

type KnowledgeBase 

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

* KnowledgeBase is a SQLite3-backed store for projects, observations, and

  • concepts. The database file is created automatically on first use at
  • whatever path Open is given. *
  • Example:
  • kb, err := Open(DefaultPath(root))
  • if err != nil {
  • log.Fatal(err)
  • }
  • defer kb.Close()

func Open 

func Open(dbPath string) (*KnowledgeBase, error)

* Open opens (or creates) the SQLite knowledge base at dbPath. The schema

  • is applied on every open so that tables are created on first use without
  • manual migration. *
  • Parameters:
  • dbPath (string) — full path to the knowledge.db file. *
  • Returns:
  • *KnowledgeBase — ready-to-use knowledge base handle.
  • error — if the database file cannot be opened or the schema
  • cannot be applied. *
  • Example:
  • kb, err := Open(DefaultPath("/home/user/myproject"))
  • if err != nil {
  • log.Fatal(err)
  • }
  • defer kb.Close()

func (*KnowledgeBase) AddConcept 

func (kb *KnowledgeBase) AddConcept(name, description string) (int64, error)

* AddConcept inserts a new concept or, if a concept with the same name exists,

  • returns its ID unchanged. It is equivalent to calling AddConceptWithIdentifier
  • with identifierType = identifierValue = "", which leaves any identifier
  • already recorded for an existing concept untouched. *
  • Parameters:
  • name (string) — unique concept name.
  • description (string) — human-readable explanation of the concept. *
  • Returns:
  • int64 — ID of the inserted or existing concept.
  • error — on database failure. *
  • Example:
  • id, err := kb.AddConcept("WAL mode", "SQLite write-ahead logging for concurrency")

func (*KnowledgeBase) AddConceptWithIdentifier 

func (kb *KnowledgeBase) AddConceptWithIdentifier(name, description, identifierType, identifierValue string) (int64, error)

* AddConceptWithIdentifier inserts a new concept, or updates an existing

  • concept with the same name, optionally recording a scholarly identifier
  • (e.g. a paper's DOI, a person's ORCID, an institution's ROR) that the
  • concept represents. If identifierType or identifierValue is "" on an
  • update, the existing stored value (if any) is preserved rather than
  • cleared. *
  • Parameters:
  • name (string) — unique concept name.
  • description (string) — human-readable explanation of the concept.
  • identifierType (string) — one of the IdentifierType values (e.g. "doi", "orcid"), or "".
  • identifierValue (string) — normalized (extended) identifier value, or "". *
  • Returns:
  • int64 — ID of the inserted or existing concept.
  • error — on database failure. *
  • Example:
  • id, err := kb.AddConceptWithIdentifier("Jane Doe", "paper author",
  • string(IdentifierORCID), "0000-0003-0900-6903")

func (*KnowledgeBase) AddObservation 

func (kb *KnowledgeBase) AddObservation(projectID int64, kind, body string) (int64, error)

* AddObservation inserts a new observation for a project and returns its ID.

  • It is equivalent to calling AddObservationWithSource with sourceDOI = "". *
  • Parameters:
  • projectID (int64) — ID of the owning project.
  • kind (string) — one of: note, finding, decision, question, hypothesis.
  • body (string) — the observation text. *
  • Returns:
  • int64 — ID of the new observation.
  • error — if kind is invalid or the insert fails. *
  • Example:
  • id, err := kb.AddObservation(1, "finding", "WAL mode doubles write throughput")

func (*KnowledgeBase) AddObservationWithSource 

func (kb *KnowledgeBase) AddObservationWithSource(projectID int64, kind, body, sourceDOI string) (int64, error)

* AddObservationWithSource inserts a new observation for a project,

  • recording the normalized DOI of the paper it was extracted from, and
  • returns its ID. *
  • Parameters:
  • projectID (int64) — ID of the owning project.
  • kind (string) — one of: note, finding, decision, question, hypothesis.
  • body (string) — the observation text.
  • sourceDOI (string) — normalized DOI of the source paper, or "" if none. *
  • Returns:
  • int64 — ID of the new observation.
  • error — if kind is invalid or the insert fails. *
  • Example:
  • id, err := kb.AddObservationWithSource(1, "finding",
  • "This paper found X", "https://doi.org/10.1234/abcd.5678")

func (*KnowledgeBase) AddProject 

func (kb *KnowledgeBase) AddProject(name, description string) (int64, error)

* AddProject inserts a new project row and returns its auto-assigned ID. If a

  • project with the same name already exists, its ID is returned instead. *
  • Parameters:
  • name (string) — unique project name.
  • description (string) — short human-readable description. *
  • Returns:
  • int64 — ID of the inserted or existing project.
  • error — on database failure. *
  • Example:
  • id, err := kb.AddProject("harvey", "Terminal coding agent backed by Ollama")

func (*KnowledgeBase) AddProjectWithStatus added in v0.0.2 

func (kb *KnowledgeBase) AddProjectWithStatus(name, description, status string) (int64, error)

* AddProjectWithStatus is like AddProject but sets an explicit status

  • instead of the "active" default. status must be one of concept, active,
  • paused, or concluded. *
  • Parameters:
  • name (string) — unique project name.
  • description (string) — short human-readable description.
  • status (string) — one of concept, active, paused, concluded. *
  • Returns:
  • int64 — ID of the inserted or existing project. If the project already
  • existed, its status is left unchanged (same no-op convention
  • as AddProject).
  • error — on database failure, or if status is not one of the allowed values. *
  • Example:
  • id, err := kb.AddProjectWithStatus("harvey", "Terminal coding agent", "concept")

func (*KnowledgeBase) AddSource 

func (kb *KnowledgeBase) AddSource(s Source) (int64, error)

* AddSource inserts a new source row and returns its auto-assigned ID.

  • When identifier_type and identifier_value are both non-empty, an existing
  • row with the same (type, value) pair is returned instead of creating a
  • duplicate. *
  • Parameters:
  • s (Source) — source metadata; ID field is ignored. *
  • Returns:
  • int64 — the ID of the inserted or existing row.
  • error — on database failure. *
  • Example:
  • id, err := kb.AddSource(Source{Title: "SPARQL 1.1", IdentifierType: "doi", IdentifierValue: "10.1234/sparql"})

func (*KnowledgeBase) CheckRetractions 

func (kb *KnowledgeBase) CheckRetractions(
	checker func(doi string) (retracted bool, note string, err error),
	out io.Writer,
) (checked, updated int, err error)

* CheckRetractions queries checker for every non-retracted source with

  • identifier_type = "doi" and marks any hits as retracted. It also updates
  • last_checked_at for every source it queries. Progress is written to out. *
  • Parameters:
  • checker (func(doi string) (bool, string, error)) — returns (retracted,
  • note, err) for a given DOI. Use CheckDOIRetraction for production.
  • out (io.Writer) — destination for per-source status lines. *
  • Returns:
  • checked (int) — number of DOI sources queried.
  • updated (int) — number of sources newly marked as retracted.
  • error — on database failure (checker errors are logged, not fatal). *
  • Example:
  • checked, updated, err := kb.CheckRetractions(
  • func(doi string) (bool, string, error) {
  • return CheckDOIRetraction(doi, DefaultRetractionWatchURL)
  • }, os.Stdout)

func (*KnowledgeBase) Close 

func (kb *KnowledgeBase) Close() error

* Close releases the database connection. It should be deferred immediately

  • after a successful Open call. *
  • Returns:
  • error — from the underlying sql.DB.Close call. *
  • Example:
  • kb, _ := Open(dbPath)
  • defer kb.Close()

func (*KnowledgeBase) Concepts 

func (kb *KnowledgeBase) Concepts() ([]Concept, error)
  • Concepts returns all concepts ordered by name. *
  • Returns:
  • []Concept — all concept rows; empty (not nil) if none exist.
  • error — on database failure. *
  • Example:
  • concepts, err := kb.Concepts()
  • for _, c := range concepts {
  • fmt.Println(c.Name)
  • }

func (*KnowledgeBase) FindOrCreateSource 

func (kb *KnowledgeBase) FindOrCreateSource(title, identifierType, identifierValue string) (int64, error)

* FindOrCreateSource upserts a source by identifier when one is provided, or

  • inserts a new source with the given title when no identifier is known. *
  • Parameters:
  • title (string) — human-readable title or file path.
  • identifierType (string) — "doi", "url", etc.; empty = no identifier.
  • identifierValue (string) — the identifier value; empty = no identifier. *
  • Returns:
  • int64 — the ID of the found or created source.
  • error — on database failure. *
  • Example:
  • id, err := kb.FindOrCreateSource("spec.md", "doi", "10.1234/example")

func (*KnowledgeBase) FormatMarkdown 

func (kb *KnowledgeBase) FormatMarkdown(projectID int64) (string, error)

* FormatMarkdown returns the knowledge base contents as Markdown, suitable for

  • injecting into a conversation as context. When projectID > 0 only that project
  • is included; when projectID == 0 all projects are included. Each project gets
  • a ## heading, and observations are listed with their kind in bold. *
  • Parameters:
  • projectID (int64) — project to export; 0 = all projects. *
  • Returns:
  • string — Markdown-formatted knowledge base contents; "" if no data.
  • error — on database failure. *
  • Example:
  • md, err := kb.FormatMarkdown(0) // all projects
  • md, err := kb.FormatMarkdown(1) // project id=1 only

func (*KnowledgeBase) LinkObservationConcept 

func (kb *KnowledgeBase) LinkObservationConcept(observationID, conceptID int64) error

* LinkObservationConcept associates an observation with a concept. Duplicate

  • links are silently ignored. *
  • Parameters:
  • observationID (int64) — ID of the observation.
  • conceptID (int64) — ID of the concept. *
  • Returns:
  • error — on database failure. *
  • Example:
  • err := kb.LinkObservationConcept(obsID, conceptID)

func (*KnowledgeBase) LinkObservationSource 

func (kb *KnowledgeBase) LinkObservationSource(observationID, sourceID int64, relationship string) error

* LinkObservationSource creates an observation_sources row linking an

  • observation to a source. Duplicate links are silently ignored. *
  • Parameters:
  • observationID (int64) — observation primary key.
  • sourceID (int64) — source primary key.
  • relationship (string) — label, e.g. "cited" or "retrieved". *
  • Returns:
  • error — on database failure. *
  • Example:
  • err := kb.LinkObservationSource(42, 1, "retrieved")

func (*KnowledgeBase) LinkProjectConcept 

func (kb *KnowledgeBase) LinkProjectConcept(projectID, conceptID int64) error

* LinkProjectConcept associates a project with a concept. Duplicate links are

  • silently ignored. *
  • Parameters:
  • projectID (int64) — ID of the project.
  • conceptID (int64) — ID of the concept. *
  • Returns:
  • error — on database failure. *
  • Example:
  • err := kb.LinkProjectConcept(projectID, conceptID)

func (*KnowledgeBase) ListSources 

func (kb *KnowledgeBase) ListSources() ([]Source, error)
  • ListSources returns all rows in the sources table, ordered by id. *
  • Returns:
  • []Source — all sources; empty slice when none exist.
  • error — on database failure. *
  • Example:
  • sources, err := kb.ListSources()

func (*KnowledgeBase) ObservationByID 

func (kb *KnowledgeBase) ObservationByID(id int64) (*Observation, error)
  • ObservationByID returns a single observation by its id. *
  • Parameters:
  • id (int64) — the observation's id. *
  • Returns:
  • *Observation — the matching observation.
  • error — sql.ErrNoRows if no observation has that id, or on
  • database failure. *
  • Example:
  • o, err := kb.ObservationByID(42)
  • if err != nil {
  • // not found or DB error
  • }

func (*KnowledgeBase) ObservationSources 

func (kb *KnowledgeBase) ObservationSources(observationID int64) ([]Source, error)

* ObservationSources returns all sources linked to the given observation id,

  • including retraction state, ordered by source id. *
  • Parameters:
  • observationID (int64) — observation primary key. *
  • Returns:
  • []Source — linked sources; empty slice when none.
  • error — on database failure. *
  • Example:
  • sources, err := kb.ObservationSources(42)

func (*KnowledgeBase) Observations 

func (kb *KnowledgeBase) Observations(projectID int64) ([]Observation, error)
  • Observations returns all observations for a project, newest first. *
  • Parameters:
  • projectID (int64) — ID of the project to query. *
  • Returns:
  • []Observation — slice of matching rows; empty (not nil) if none exist.
  • error — on database failure. *
  • Example:
  • obs, err := kb.Observations(1)
  • for _, o := range obs {
  • fmt.Printf("[%s] %s\n", o.Kind, o.Body)
  • }

func (*KnowledgeBase) Path 

func (kb *KnowledgeBase) Path() string

Path returns the absolute path of the open knowledge base file.

func (*KnowledgeBase) ProjectByName 

func (kb *KnowledgeBase) ProjectByName(name string) (*Project, error)
  • ProjectByName returns the project with the given name, or nil if not found. *
  • Parameters:
  • name (string) — exact project name. *
  • Returns:
  • *Project — the matching project, or nil.
  • error — on database failure. *
  • Example:
  • p, err := kb.ProjectByName("harvey")

func (*KnowledgeBase) ProjectConcepts 

func (kb *KnowledgeBase) ProjectConcepts(projectID int64) ([]Concept, error)
  • ProjectConcepts returns all concepts linked to a project, ordered by name. *
  • Parameters:
  • projectID (int64) — ID of the project. *
  • Returns:
  • []Concept — linked concepts; empty (not nil) if none.
  • error — on database failure. *
  • Example:
  • concepts, err := kb.ProjectConcepts(1)

func (*KnowledgeBase) Projects 

func (kb *KnowledgeBase) Projects() ([]Project, error)
  • Projects returns all projects ordered by creation date. *
  • Returns:
  • []Project — slice of all project rows; empty (not nil) if none exist.
  • error — on database failure. *
  • Example:
  • projects, err := kb.Projects()
  • for _, p := range projects {
  • fmt.Println(p.Name, p.Status)
  • }

func (*KnowledgeBase) RemoveSource 

func (kb *KnowledgeBase) RemoveSource(id int64) error

* RemoveSource deletes the source with the given id. Returns an error if the

  • source is linked to any observations. *
  • Parameters:
  • id (int64) — source primary key. *
  • Returns:
  • error — if the source is linked or not found. *
  • Example:
  • err := kb.RemoveSource(1) // fails if linked

func (*KnowledgeBase) RetractSource 

func (kb *KnowledgeBase) RetractSource(id int64, note string) error

* RetractSource sets retracted=1 and records a retraction note on the source

  • with the given id. *
  • Parameters:
  • id (int64) — source primary key.
  • note (string) — free-text retraction note. *
  • Returns:
  • error — on database failure. *
  • Example:
  • err := kb.RetractSource(1, "Retracted 2026-07-01 by publisher")

func (*KnowledgeBase) Search 

func (kb *KnowledgeBase) Search(term string) ([]KBSearchResult, error)

* Search performs a full-text search across observations, projects, and concepts

  • using the FTS5 index. Results are ranked by relevance (best match first).
  • Returns an error wrapping ErrFTSUnavailable when the FTS index is not present. *
  • The term uses standard FTS5 query syntax: multiple words are ANDed, phrases
  • can be quoted ("WAL mode"), and prefix search is supported (docker*). *
  • Parameters:
  • term (string) — FTS5 query term. *
  • Returns:
  • []KBSearchResult — ranked results; nil if none found.
  • error — on query failure or when FTS is unavailable. *
  • Example:
  • results, err := kb.Search("docker")
  • for _, r := range results {
  • fmt.Printf("[%-10s] %s — %s\n", r.Kind, r.Label, r.Snippet)
  • }

func (*KnowledgeBase) SetProjectStatus added in v0.0.2 

func (kb *KnowledgeBase) SetProjectStatus(name, status string) error

* SetProjectStatus updates an existing project's status. status must be

  • one of concept, active, paused, or concluded. *
  • Parameters:
  • name (string) — the project's unique name.
  • status (string) — one of concept, active, paused, concluded. *
  • Returns:
  • error — if status is invalid, the project does not exist, or on
  • database failure. *
  • Example:
  • err := kb.SetProjectStatus("harvey", "paused")

func (*KnowledgeBase) ShowSource 

func (kb *KnowledgeBase) ShowSource(id int64) (*Source, error)

* ShowSource returns the full source row for the given id, or an error if

  • not found. *
  • Parameters:
  • id (int64) — source primary key. *
  • Returns:
  • *Source — the source row.
  • error — sql.ErrNoRows when not found; other errors on db failure. *
  • Example:
  • s, err := kb.ShowSource(1)

func (*KnowledgeBase) Summary 

func (kb *KnowledgeBase) Summary() (string, error)

* Summary returns a human-readable text summary of all projects and their

  • recent observations, suitable for printing in the Harvey REPL. *
  • Returns:
  • string — formatted multi-line summary.
  • error — on database failure. *
  • Example:
  • s, err := kb.Summary()
  • fmt.Print(s)

type MergeTableSummary 

type MergeTableSummary struct {
	Table  string
	FromA  int
	FromB  int
	Merged int
}

* MergeTableSummary reports, per table, how many rows came from each

  • source and how many rows the merged table ended up with (less than
  • FromA+FromB when uuid or name collisions caused an intentional drop).

func MergeKnowledgeBases 

func MergeKnowledgeBases(aPath, bPath, mergedPath string) ([]MergeTableSummary, error)

* MergeKnowledgeBases creates a fresh knowledge base at mergedPath (which

  • must not already exist) containing the set union of aPath and bPath,
  • deduped by uuid (and, for projects/concepts, by the pre-existing name
  • UNIQUE constraint). aPath and bPath are opened read-only via ATTACH;
  • neither is modified. *
  • Parameters:
  • aPath (string) — path to the first source knowledge.db.
  • bPath (string) — path to the second source knowledge.db.
  • mergedPath (string) — path for the new merged knowledge.db; must not exist. *
  • Returns:
  • []MergeTableSummary — per-table row counts; nil until wired in a later work item.
  • error — on database failure, or if mergedPath already exists. *
  • Example:
  • summary, err := MergeKnowledgeBases("/machine-a/knowledge.db", "/machine-b/knowledge.db", "/tmp/merged.db")

type NameCollision 

type NameCollision struct {
	Table string // "projects" or "concepts"
	Name  string
	UUIDA string
	UUIDB string
}

* NameCollision is a projects.name or concepts.name value that exists

  • independently in both source databases under two different uuids —
  • almost certainly the same real-world entity, created before the UUID
  • migration, now indistinguishable by name alone. *
  • Example:
  • collisions, _ := CollisionReport("a.db", "b.db")
  • for _, c := range collisions {
  • fmt.Printf("%s %q: %s vs %s\n", c.Table, c.Name, c.UUIDA, c.UUIDB)
  • }

func CollisionReport 

func CollisionReport(aPath, bPath string) ([]NameCollision, error)

* CollisionReport opens aPath and bPath read-only and reports every

  • projects/concepts name that exists in both under different uuids.
  • Callers should review (and resolve, out of band) any collisions before
  • calling MergeKnowledgeBases — a collision is silently resolved
  • "first insert wins" by MergeKnowledgeBases's INSERT OR IGNORE, which may
  • not be the row the caller wants to keep. *
  • Parameters:
  • aPath (string) — path to the first knowledge.db.
  • bPath (string) — path to the second knowledge.db. *
  • Returns:
  • []NameCollision — one entry per colliding name; empty if none found.
  • error — on database failure. *
  • Example:
  • collisions, err := CollisionReport("/machine-a/knowledge.db", "/machine-b/knowledge.db")

type Observation 

type Observation struct {
	ID        int64
	ProjectID int64
	Kind      string
	Body      string
	SourceDOI string
	CreatedAt time.Time
}

* Observation represents a single timestamped note, finding, decision,

  • question, or hypothesis attached to a project. SourceDOI records the
  • normalized DOI of the paper the observation was extracted from, if any;
  • it is "" for observations not tied to a specific source document. *
  • Example:
  • obs, err := kb.Observations(projectID)
  • for _, o := range obs {
  • fmt.Printf("[%s] %s\n", o.Kind, o.Body)
  • }

type Project 

type Project struct {
	ID          int64
	Name        string
	Description string
	Status      string
	CreatedAt   time.Time
}
  • Project represents a single project row in the knowledge base. *
  • Example:
  • projects, err := kb.Projects()
  • for _, p := range projects {
  • fmt.Printf("%d %s [%s]\n", p.ID, p.Name, p.Status)
  • }

type Source 

type Source struct {
	ID              int64
	Title           string
	IdentifierType  string
	IdentifierValue string
	Authors         string
	PublishedDate   string
	Publisher       string
	Rights          string
	Version         string
	Retracted       bool
	RetractionNote  string
}

* Source is a row in the sources authority table. Each source represents a

  • citable document or resource that may be linked to observations. *
  • Fields:
  • ID (int64) — auto-assigned primary key.
  • Title (string) — human-readable title.
  • IdentifierType (string) — "doi", "url", "isbn", "issn", "arxiv", "urn", or "".
  • IdentifierValue (string) — the identifier string, e.g. "10.1234/example".
  • Authors (string) — comma-separated author names.
  • PublishedDate (string) — publication date, YYYY-MM-DD format.
  • Publisher (string) — publisher name.
  • Rights (string) — licence or rights statement.
  • Version (string) — edition or version.
  • Retracted (bool) — true when the source has been retracted.
  • RetractionNote (string) — free-text note about the retraction. *
  • Example:
  • s := Source{Title: "SPARQL 1.1", IdentifierType: "doi", IdentifierValue: "10.1234/sparql"}
  • id, err := kb.AddSource(s)

Source Files

View all Source files

Directories

Path Synopsis
cmd
kb command
kb is a command-line and interactive (TUI) interface for a github.com/rsdoiel/knowledge knowledge base.
 kb is a command-line and interactive (TUI) interface for a github.com/rsdoiel/knowledge knowledge base.

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.