Skip to main content
Knapset logo

Knapset v2

Knapset is a zero-dependency, pure Python Standard Library tool (ks / knapset) for turning your existing SQLite databases, CSV/TSV sheets, and JSON/JSONL datasets into ranked decisions, optimal baskets, or compatible multi-part sets using signed preference weights, safe custom formulas, Reference DB matching, and multi-resource limits.

No SQL query boilerplate, no vendor spreadsheets, no pip install dependency trees.

Existing DBs (.db / .csv / .json) ──► Reference DB Enricher (--ref) ──► Safe AST Formulas & Weights
                                                                              │
            ┌───────────────────────────┬──────────────────────────┬──────────┴─────────────┐
            ▼                           ▼                          ▼                        ▼
       ks rank (Top-K)        ks basket (Knapsack)       ks solve (Multi-Slot)     ks tui (curses) / ks serve / ks mcp

Key Features

  • Read-Only Multi-Format Ingestion (sources/): Opens SQLite databases (?mode=ro + PRAGMA query_only = ON, single read-only SELECT/WITH), CSV, TSV, JSON, and JSONL automatically.
  • Cross-Database Matching & Enrichment (enricher.py, --ref, ks compare): Attach Reference DBs (benchmark tables, MSRP price sheets, calorie tables) onto candidate listings using exact, specificity-ordered token, or regex matching, exposed under ref.* (e.g. ref.score, ref.msrp).
  • Safe AST Formulas, Filters, Weights & Limits (formula_engine.py):
    • Derived formulas: --formula "deal_pct = (ref.msrp - price) / ref.msrp * 100"
    • Signed preference weights: --prefer "ref.score:+0.7, price:-0.3" with automatic min-max [0, 1] normalization and --explain breakdown
    • Multi-resource limits: --limit "sum(price) <= 950", --limit "sum(weight_g) <= 2000", --limit "count <= 5"
    • Cross-slot compatibility rules: --rule "cpu.socket == mobo.socket", --rule "cpu.score / gpu.ref.score < 1"
  • Three Optimization Modes (solver_engine.py):
    • ks rank: Single-table Top-K ranking with --explain normalized breakdown.
    • ks basket: 0/1 or bounded multi-item knapsack under multiple resource caps.
    • ks solve: Multi-slot set composition across tables or separate files.
  • Interactive curses TUI (ks tui): Pick main & reference DBs, switch presets/profiles, switch live color themes via /theme in the command palette, nudge weights live with ←/→ or -/+ (keyboard or mouse hold), type custom formulas/rules/limits inline with discovered column hints, see top results update live, and save customized .json presets.
  • Registry, Presets & TUI Themes (ks reg, ks preset, configs/theme.json): Save/share declarative .json (or .toml on Python 3.11+) presets, configure or switch TUI color themes in configs/theme.json (supporting named ANSI, 256-color indices, and #RRGGBB hex colors, with built-in agy-dark and soft-dark-pink), or search/install/verify community presets and themes via knapset-registry (ks reg).
  • Web Studio (ks serve) & MCP Server (ks mcp): Built-in local browser dashboard + JSON API (http.server) and zero-dependency JSON-RPC 2.0 MCP server over stdio.

Requirements

  • Python 3.10+ (Linux, macOS, WSL, Windows; on Windows, ks tui requires windows-curses or use ks serve / CLI flags).
  • Zero external Python dependencies (100% Python Standard Library).

Quick Start

# 1. Inspect tables, column types, and numeric ranges in any SQLite/CSV/JSON file
ks inspect market.db

# 2. Match candidates against a Reference DB and preview coverage
ks compare gpus.csv --ref gpu_benchmarks.csv --match title~model --on-unmatched drop

# 3. Rank rows with formulas, filters, signed weights, and normalized explanation
ks rank gpus.csv --ref gpu_benchmarks.csv --match title~model \
  --formula "val = ref.score / price" \
  --where "price <= 600" \
  --prefer "val:+0.7, price:-0.3" --explain

# 4. Pack a multi-item basket under resource limits (knapsack)
ks basket snacks.csv --limit "sum(price) <= 15" --limit "sum(weight_g) <= 500" --prefer "protein:+0.8, price:-0.2"

# 5. Synthesize multi-slot combinations across tables with AST rules
ks solve pc.db --tables cpu,mobo,gpu,psu \
  --rule "cpu.socket == mobo.socket" \
  --rule "psu.wattage >= (cpu.tdp + gpu.tdp) * 1.25" \
  --rule "cpu.score / gpu.score < 1" \
  --limit "sum(price) <= 950" \
  --prefer "gpu.score:+0.5, cpu.score:+0.3, price:-0.2" --export results.csv

# 6. Interactive Terminal UI (+ / - weights, custom rules/formulas, save preset)
ks tui pc.db

# 7. Scaffold & execute reusable JSON presets
ks init pc.db -o my_pc.json
ks run my_pc.json --prefer "price:-0.6" --limit "sum(price) <= 800"

# 8. Browse, install & activate TUI themes or presets from knapset-registry
ks reg search --type theme
ks reg install theme:nord --use
ks reg theme list
ks reg theme use soft-dark-pink

# 9. Reuse saved preferences across DBs with the same column names
#    In the TUI: `s` saves to ~/.config/knapset/profiles/, `l` (or /profiles) applies a saved profile
#    (or loads one from any profile/preset file) onto whatever DB is open.
ks tui other_shop.db --prefs my_prefs

#    CLI: manage the library and apply it to rank / basket / solve
ks prefs list
ks prefs save quality -p "score:+0.8,price:-0.2" -w "price > 0"
ks prefs import my_preset.json --name quality     # from a profile file or any preset
ks prefs export quality ./quality.json
ks rank other_shop.csv --prefs quality --top 5     # explicit flags override the profile

Development & Tests

git clone https://github.com/knapset-dev/knapset.git
cd knapset
python3 -m unittest discover -s tests -v

Licensed under the MIT License (LICENSE).

Metadata

Release files for knapset 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for knapset 2.0.0
File Size Uploaded Provenance Actions
knapset-2.0.0.tar.gz 931.3 kB With provenance Details for knapset-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for knapset 2.0.0
File Interpreter ABI Platform Actions
knapset-2.0.0-py3-none-any.whl Python 3 none any Details for knapset-2.0.0-py3-none-any.whl

Total release size: 1.0 MB

Release files / knapset-2.0.0.tar.gz

Download URL knapset-2.0.0.tar.gz
Size 931.3 kB
Tags Source
SHA-256 checksum
How to use checksums
dc926f74608124d4c8aeecf9567e3d0234308a48e5d3689c05d1ef501b1bb188
BLAKE2b-256 checksum
How to use checksums
d1439dda2145d91d8489005d216adea48a580ae6d1983cf2af7faa2ff3b03edb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / knapset-2.0.0-py3-none-any.whl

Download URL knapset-2.0.0-py3-none-any.whl
Size 117.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0697720af96d45d636ddff801a691d12d03f5799afa972820b8602dcf0ebab6d
BLAKE2b-256 checksum
How to use checksums
807f8f934705b32da079a8363ec1fe7ceabd2200ceead4344592231d575cbaaa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for knapset 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for knapset-2.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page