symaira-corekit

module
v0.17.0 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2026 License: Apache-2.0

README

Symaira CoreKit

CI Latest release License

Symaira CoreKit social preview

Shared Go library for the Symaira Go tools (symbrain, symdesk, symbrowse, symvault, symfritz, symvibe).

Status: pre-1.0 — see CHANGELOG.md.

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.

go get github.com/danieljustus/symaira-corekit@latest

Although corekit is a Go library, its conventions also guide the non-Go tools (symcockpit, symterminal, symeraseme). See docs/cross-language-conventions.md for the shared contracts that apply across languages.

Why CoreKit

  • Standalone-first: every package works without any other Symaira tool installed — optional integrations are runtime contracts, never build-time imports.
  • CGO-free: 100% pure Go on linux/darwin/windows (amd64+arm64); no platform toolchain required.
  • Cross-language conventions: exit codes, XDG paths, env-var naming, and MCP stdio framing are shared contracts that also guide the Swift and Python free tools.
  • Strict SemVer: API stability is guaranteed within major versions; consumers pin the module in go.mod.
  • Domain-free: no Vault crypto, Memory PII rules, Seek ranking, Fetch fingerprinting, Scope scanning, or cloud/SaaS primitives.

Install

go get github.com/danieljustus/symaira-corekit@latest

Import any package individually; each one is independently usable:

import "github.com/danieljustus/symaira-corekit/logkit"

Consumers pin the module version in go.mod — see Versioning.

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, billing, and other product- or cloud-specific behavior.

Packages

Package Since Purpose
auditkit v0.11.0 Tamper-evident SHA-256 hash-chain audit log with anchor checkpoints and size-based rotation
configkit v0.1.0 TOML config loader with XDG paths, project overrides, and env vars
domkit v0.9.0 Shared semantic DOM pipeline for schema, selector, image, truncation, and markdown extraction
envutil v0.1.0 Safe environment variable access with alias support
evidencekit v0.4.0 Grounded extraction contract (SourceRef, Span, Extraction, AlignmentStatus), JSONL sidecar encode/decode, exact/normalized text-span alignment, and grounded-only validation
exitcodes v0.1.0 Typed exit codes (ExitOK, ExitGeneric, ExitNoInput, ExitNoAuth, ExitForbidden, ExitNotFound, ExitConflict, ExitSoftware, ExitData, ExitConfig, ExitInterrupted) and CLIError type; see contracts/exit_codes.json
fsutil v0.1.0 Atomic file writes, path traversal validation, temp-file safety
llmkit v0.14.0 Shared LLM provider layer: descriptor-driven registry, one OpenAI transport plus an Anthropic dialect, streaming, tool use, embeddings, model discovery, credential references (symvault:///env://), and the contract error taxonomy
logkit v0.1.0 Structured logging (log/slog) to stderr, configurable via SYM<APP>_LOG_LEVEL
mcpcfgkit v0.10.0 MCP server config discovery across AI client applications (JSONC/JSON/YAML)
mcpserver v0.1.0 Generic JSON-RPC 2.0 stdio server for MCP tool registration
ollamakit v0.4.1 Deprecated: superseded by llmkit (Ollama is now a provider descriptor); thin shim, removal after one minor release
sqlitekit v0.1.0 modernc.org/sqlite wrapper with WAL mode and embedded migrations
updatecheck v0.1.0 GitHub release checker (opt-in, max 1×/24h)
updatecheck/cosign v0.6.0 Cosign keyless signature verification for release checksums (Repo/BinaryName/IdentityRegexp parametrisierbar)
updatecheck/extract v0.6.0 Safe archive extraction (tar.gz/zip) with path-traversal protection
updatecheck/installmethod v0.6.0 Install-method detection: Homebrew, go install, package-manager, direct-download, build-from-source
updatecheck/updateapply v0.5.0 Self-update installer: matching-asset download, checksum verification, atomic replacement with rollback, re-exec, and optional Cosign verification, archive extraction, install-method detection, and post-swap executable validation
vectorkit/turboquant v0.2.0 CGO-free TurboQuant scalar vector quantization: deterministic rotation, packed encode/decode, inner-product/cosine scoring, sidecar metadata, benchmarks
versionkit v0.3.0 Standardized handshake payload ({tool, version, schema_version}) for CLI tools

Install the module with go get github.com/danieljustus/symaira-corekit@latest — see Install.

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")

Documentation

Versioning

Strict SemVer. Each tool pins its corekit version in go.mod.

Update expectation: a consumer pins a version deliberately, but is expected to move to the latest compatible minor release no later than that consumer's own next release. Pinning is for stability between releases, not a license to fall permanently behind. See docs/migrations.md for what changed in each minor release since v0.3.0.

Run make consumer-drift (or scripts/consumer-drift.sh) from this repo to list every sibling Symaira repo checked out alongside it and the corekit version each one currently pins.

Contributing · Security · License

Licensed under the Apache-2.0 license. See LICENSE.

Directories

Path Synopsis
Package auditkit provides the shared audit-log infrastructure for Symaira tools: a tamper-evident hash chain over JSONL entries and an append-only file sink with size-based rotation.
 Package auditkit provides the shared audit-log infrastructure for Symaira tools: a tamper-evident hash chain over JSONL entries and an append-only file sink with size-based rotation.
Package configkit provides generic TOML configuration loading with env var overrides.
 Package configkit provides generic TOML configuration loading with env var overrides.
Package domkit provides the shared semantic DOM pipeline for the Symaira fetch/browse family (issue X-3): HTML→Markdown rendering, outline extraction, output schema, truncation and content-boundary markers.
 Package domkit provides the shared semantic DOM pipeline for the Symaira fetch/browse family (issue X-3): HTML→Markdown rendering, outline extraction, output schema, truncation and content-boundary markers.
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 llmkit provides the shared LLM provider layer for the Symaira Go tools, implementing docs/llm-provider-contract.md.
 Package llmkit provides the shared LLM provider layer for the Symaira Go tools, implementing docs/llm-provider-contract.md.
gen command
Command gen regenerates llmkit/providers.json from the shared contract source of truth in contracts/llm_providers.json.
 Command gen regenerates llmkit/providers.json from the shared contract source of truth in contracts/llm_providers.json.
Package logkit provides structured logging helpers for CLI applications.
 Package logkit provides structured logging helpers for CLI applications.
Package mcpcfgkit provides MCP server config discovery across AI client applications.
 Package mcpcfgkit provides MCP server config discovery across AI client 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 compatibility surface for the shared Ollama provider in llmkit.
 Package ollamakit provides a compatibility surface for the shared Ollama provider in llmkit.
Package secretref resolves the shared secret-reference format used across the Symaira Go tools:
 Package secretref resolves the shared secret-reference format used across the Symaira Go 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.

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.