README
¶
symaira-corekit
Shared Go library for the Symaira public-core tools (symvault, symmemory, symseek, symfetch, symscope).
Bundles domain-free infrastructure that is otherwise duplicated across tools: MCP server scaffold, TOML config loading, exit codes, logging, path safety, SQLite setup, and update checking.
Although corekit is a Go library, its conventions also guide the non-Go free tools (symoperate, symtune, symterminal, symeraseme). See docs/cross-language-conventions.md for the shared contracts that apply across languages.
Standalone-First Contract
Corekit is a shared foundation, not a runtime dependency graph between products. Consumers must keep working when every other Symaira tool is absent. Optional cross-tool behavior belongs behind runtime detection and fallback in the consumer, not as imports from sibling tool repositories.
Corekit must stay free of Vault crypto, Memory PII policy, Seek ranking, Fetch fingerprinting, Scope port scanning, Pro billing, Firebase, Stripe, GCP SDKs, and other product- or cloud-specific behavior.
Packages
| Package | Purpose |
|---|---|
exitcodes |
Typed exit codes (ExitOK, ExitError, ExitUsage, ExitAuth) and CLIError type |
logkit |
Structured logging (log/slog) to stderr, configurable via SYM<APP>_LOG_LEVEL |
envutil |
Safe environment variable access with alias support |
fsutil |
Atomic file writes, path traversal validation, temp-file safety |
configkit |
TOML config loader with XDG paths, project overrides, and env vars |
evidencekit |
Grounded extraction contract (SourceRef, Span, Extraction, AlignmentStatus), JSONL sidecar encode/decode, exact/normalized text-span alignment, and grounded-only validation |
mcpserver |
Generic JSON-RPC 2.0 stdio server for MCP tool registration |
ollamakit |
CGO-free shared Ollama HTTP client: embeddings, streamed generation/chat, model discovery, and typed errors |
sqlitekit |
modernc.org/sqlite wrapper with WAL mode and embedded migrations |
updatecheck |
GitHub release checker (opt-in, max 1×/24h) |
updatecheck/updateapply |
Self-update installer: matching-asset download, checksum verification, atomic replacement with rollback, re-exec, and optional Cosign verification, archive extraction, and install-method detection |
updatecheck/cosign |
Cosign keyless signature verification for release checksums (Repo/BinaryName/IdentityRegexp parametrisierbar) |
updatecheck/extract |
Safe archive extraction (tar.gz/zip) with path-traversal protection |
updatecheck/installmethod |
Install-method detection: Homebrew, go install, package-manager, direct-download, build-from-source |
vectorkit/turboquant |
CGO-free TurboQuant scalar vector quantization: deterministic rotation, packed encode/decode, inner-product/cosine scoring, sidecar metadata, benchmarks |
versionkit |
Standardized handshake payload ({tool, version, schema_version}) for CLI tools |
Usage
import "github.com/danieljustus/symaira-corekit/logkit"
// Reads MYAPP_LOG_LEVEL (debug|info|warn|error, default warn) and
// MYAPP_LOG_FORMAT (text|json, default text) from the environment.
logger := logkit.NewFromEnv("myapp")
logger.Info("started", "version", "1.0.0")
Versioning
Strict SemVer. Each tool pins its corekit version in go.mod.
License
Apache-2.0 — Daniel Justus
Directories
¶
| Path | Synopsis |
|---|---|
|
Package configkit provides generic TOML configuration loading with env var overrides.
|
Package configkit provides generic TOML configuration loading with env var overrides. |
|
Package envutil provides environment variable helpers with fallback support.
|
Package envutil provides environment variable helpers with fallback support. |
|
Package evidencekit defines Symaira-wide grounded extraction contracts: a source reference, a character span, and an Extraction that ties an extracted fact back to the exact source text that justified it.
|
Package evidencekit defines Symaira-wide grounded extraction contracts: a source reference, a character span, and an Extraction that ties an extracted fact back to the exact source text that justified it. |
|
Package exitcodes provides standardized CLI exit codes and structured error types for the Symaira ecosystem.
|
Package exitcodes provides standardized CLI exit codes and structured error types for the Symaira ecosystem. |
|
Package fsutil provides safe filesystem operations including atomic writes and path validation.
|
Package fsutil provides safe filesystem operations including atomic writes and path validation. |
|
Package logkit provides structured logging helpers for CLI applications.
|
Package logkit provides structured logging helpers for CLI applications. |
|
Package mcpserver provides a JSON-RPC 2.0 server framework for the Model Context Protocol (MCP).
|
Package mcpserver provides a JSON-RPC 2.0 server framework for the Model Context Protocol (MCP). |
|
Package ollamakit provides a shared, CGO-free Ollama HTTP client for the Symaira tools.
|
Package ollamakit provides a shared, CGO-free Ollama HTTP client for the Symaira tools. |
|
Package sqlitekit provides SQLite connection management and migration support using pure-Go SQLite.
|
Package sqlitekit provides SQLite connection management and migration support using pure-Go SQLite. |
|
Package updatecheck provides GitHub release checking for CLI application updates.
|
Package updatecheck provides GitHub release checking for CLI application updates. |
|
cosign
Package cosign provides Cosign keyless signature verification for self-update workflows.
|
Package cosign provides Cosign keyless signature verification for self-update workflows. |
|
extract
Package extract provides safe archive extraction (tar.gz and zip) for self-update workflows, with path-traversal protection and configurable binary detection.
|
Package extract provides safe archive extraction (tar.gz and zip) for self-update workflows, with path-traversal protection and configurable binary detection. |
|
installmethod
Package installmethod detects how a binary was installed to determine whether self-update is safe or if the user should update via their package manager, Go toolchain, or by rebuilding from source.
|
Package installmethod detects how a binary was installed to determine whether self-update is safe or if the user should update via their package manager, Go toolchain, or by rebuilding from source. |
|
updateapply
Package updateapply implements the apply half of self-update: given an updatecheck.Release, it downloads the matching asset, verifies its checksum against the release's goreleaser checksums.txt, and atomically replaces the running binary with backup + rollback.
|
Package updateapply implements the apply half of self-update: given an updatecheck.Release, it downloads the matching asset, verifies its checksum against the release's goreleaser checksums.txt, and atomically replaces the running binary with backup + rollback. |
|
vectorkit
|
|
|
turboquant
Package turboquant implements TurboQuant-style scalar quantization for approximate nearest-neighbor vector search.
|
Package turboquant implements TurboQuant-style scalar quantization for approximate nearest-neighbor vector search. |
|
Package versionkit provides the standardized `version --json` payload for Symaira CLI tools.
|
Package versionkit provides the standardized `version --json` payload for Symaira CLI tools. |
Click to show internal directories.
Click to hide internal directories.