fieldkit

Verified-on-Spark patterns lifted from the ai-field-notes blog into one importable Python package.

Every essay in ai-field-notes ends with evidence/ — a folder of working code that produced the article's numbers. After 30+ articles the same patterns kept reappearing: the same NIM client wrapper, the same chunk-embed-store dance, the same bench harness, the same verifier-loop math. fieldkit is what those evidence/ folders look like once the boilerplate is lifted into a real package.

The blog stays the long-form rationale. fieldkit is the pip install-able surface so you can reproduce — and extend — the work without re-pasting 80 lines of NIM-client setup per article.

Install

pip install fieldkit

For the bleeding edge between releases, install from the git tag instead:

pip install "git+https://github.com/orionfold/ainative-business.github.io.git@fieldkit/v0.31.0#subdirectory=fieldkit"

Quickstart

from fieldkit.nim import NIMClient

client = NIMClient(base_url="http://localhost:8000/v1", model="meta/llama-3.1-8b-instruct")
print(client.chat([{"role": "user", "content": "Hello, Spark."}]))

What's in v0.2.0

Module	Purpose	Source articles
`fieldkit.capabilities`	Typed Python facade over `spark-capabilities.json` — KV cache math, weight bytes, inference envelope.	`kv-cache-arithmetic-at-inference`, `gpu-sizing-math-for-fine-tuning`
`fieldkit.nim`	OpenAI-compatible NIM client wrapper with retry, chunking, and the 8192-token context guard.	`nim-first-inference-dgx-spark` and friends
`fieldkit.rag`	`Pipeline(embed_url, rerank_url, pgvector_dsn, generator)` — ingest → retrieve → rerank → fuse.	`naive-rag-on-spark` and friends
`fieldkit.eval`	`Bench`, `Judge`, `Trajectory` — plus v0.2's `AssertionGrader`, `PassAtK`, `AgentRun`, `MatchedBaseComparison`.	every article with a `bench.py` or `benchmark.py`, plus `clawgym-on-spark`, `autoresearchbench-on-spark`, `pass-at-k-after-the-seventh-patch`
`fieldkit.training` (new in v0.2)	`LoraReferenceSnapshot` (sidesteps peft 0.19's offloader bug), `WeightDeltaTracker` — for any RL or SFT loop. Lazy `torch` import; pure-inference envs don't pay.	`clawgym-on-spark-grpo`
`fieldkit.cli`	`fieldkit bench rag`, `fieldkit feasibility <id>`, `fieldkit envelope <size>`.	discoverability

What v0.2 adds

fieldkit.training — new module. LoraReferenceSnapshot is a CPU-resident snapshot of a peft adapter's LoRA tensors plus a context manager that swaps the snapshot in for one no-grad forward pass and restores trainable weights on exit. Solves a real peft 0.19 bug: model.load_adapter(adapter_name="reference", is_trainable=False) crashes with KeyError under device_map="auto" whenever the GPU has anything else resident — peft's offload-detection over-triggers on Spark unified memory. WeightDeltaTracker is a pre/post snapshot of trainable params with L2 + max|Δ| reporting — sanity-check that any fine-tuning step actually moved weights.
fieldkit.eval.AssertionGrader — pure-function grader over five file-system assertion primitives (file_exists, file_not_exists, file_contents_contain, file_contents_match_regex, file_unchanged). Lifted from clawgym-on-spark's deterministic grader; no LLM, no fuzzy matching.
fieldkit.eval.PassAtK + pass_at_k_estimator — verifier-loop with the Chen 2021 unbiased pass@k estimator (lower variance than the naive 1 - (1-p)^k for finite n).
fieldkit.eval.AgentRun + TurnDetail + summarize_agent_runs — per-question agent-bench schema with overrideable field-name path tuples for non-AutoResearchBench layouts.
fieldkit.eval.MatchedBaseComparison + GroupStats — two-rollout B−A driver with per-group and per-assertion-kind delta and a markdown .report(). Reusable for any LoRA / adapter ablation, fine-tuned-vs-base, or system-prompt-A-vs-B comparison.

Deferred to v0.3+: fieldkit.agents (Persona / WorkspaceSeed / SynthTask / TaskAuthor / Sandbox / RolloutDriver / Trajectory + TurnRecord — 7 symbols), fieldkit.inference.VLLMClient, and replay_messages_from_trajectory. Each needs a second consuming article before its public API locks.

Hardware

Every code path is verified on a DGX Spark (GB10, 128 GB unified memory, NIM 8B + embed NIM + pgvector co-resident). fieldkit.training's torch + safetensors imports are lazy, so the package costs nothing on inference-only boxes — install torch and safetensors yourself in the training environment when you need the training primitives. NeMo / Triton / pytorch-base containers ship them; pure-inference envs don't.

Portability to non-Spark CUDA 12.x boxes lands when there's demand.

License

Apache-2.0. See LICENSE.

Metadata

Release files for fieldkit 0.34.1

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

Source distribution (sdist)

Source distribution for fieldkit 0.34.1
File	Size	Uploaded
fieldkit-0.34.1.tar.gz	3.4 MB	Jun 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for fieldkit 0.34.1
File	Interpreter	ABI	Platform	Reset
fieldkit-0.34.1-py3-none-any.whl 3.0 MB Jun 16, 2026	Python 3	none	any	Details

Total release size: 6.4 MB

Release files / fieldkit-0.34.1.tar.gz

Download URL	fieldkit-0.34.1.tar.gz
Size	3.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`49d3f5df76165a283b128293273af6fc0afac459150ef84bdd0df0713706bbd5`
BLAKE2b-256 checksum How to use checksums	`f8cfc6edca26f98816c6c85511a3e125e705aaf67a4ed802559fc17e6bd92d40`
Upload date	Jun 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`

Release files / fieldkit-0.34.1-py3-none-any.whl

Download URL	fieldkit-0.34.1-py3-none-any.whl
Size	3.0 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`cf83ac6ea2c94ec31fca6f083991ce21dd90a2c4648127978e1d6335d3fa3457`
BLAKE2b-256 checksum How to use checksums	`53a7fbcd665e401654411618c46b6ecb2331b5637fc48c7a877988a458497ed8`
Upload date	Jun 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`