Skip to main content

Umgodi JSON Sync Logo

umgodi-json

Umgodi is RAIkeep's actively developed Python library for distributed JSON storage with immutable history across synchronized cloud drives. Install the umgodi-json package, import umgodi, and use the continuing jpit command to seed, export, inspect, and maintain synchronized data.

Why umgodi-json?

umgodi-json is the current Python project. It replaces the historical jsonpit-python project and its jsonpit distribution, which are now frozen. The implementation continues the same storage contract under a new name so the Python identity is clear and distinct from the C# project that originated the design.

The jpit CLI remains an actively developed command-line interface. Install the new distribution with pip install umgodi-json; existing jsonpit 4.6.3 installations remain available as the frozen predecessor.

Umgodi inherits its design and storage compatibility from the C# JsonPit project, available on GitHub and NuGet. JsonPit is the heritage and cross-engine reference; Umgodi is the Python library you install and use. The C# and Python lines are intended to evolve in sync for the foreseeable future.

The Python names are intentionally distinct: inqaba is the maintained RaiKeep Python framework used heavily by Umgodi for paths, files, configuration, and related boundaries; vikela is the companion Python linter that provides guardrails for using those opinionated framework APIs safely. Both projects are recommended for application and agent code built on Umgodi.

The Zulu names express the Python line's connection to Ubuntu—both as an idea of shared human infrastructure and as a target operating-system family. The packages are not Linux-only: we test on macOS and Windows as well as Linux distributions. The complete test suite includes unit, cross-engine, and selected remote-over-SSH scenarios, providing practical confidence in the storage and synchronization behavior.

JsonPit change requests and release notes are centralized in the RAIkeep doc/ directory under JsonPit_... filenames; they are not stored separately in this child repository.

JsonPit stores JSON documents with value history across processes, machines, and servers using asynchronous persistence with eventual durability.

CLI tools: use pits (see PitSeeder) or jpit to seed, export, inspect, and maintain JsonPits. Use amafu init to detect cloud drives and create the shared RAIkeep configuration.

The canonical reference (lead) implementation is C# JsonPit and the pits CLI in RAIkeep. umgodi is the pure-Python implementation engineered for 100% behavioral and physical storage parity with zero deviation.


CR081 seed disposition receipt

Seed receipts count source entries, including repeated IDs, using the engine's accepted-fragment result:

[jpit] 3 source items: 1 written, 2 unchanged (Pit 'Object').
[jpit] 3 source items: 0 written, 3 unchanged (Pit 'Object').

A no-op exits 0. --debug / -b lists unchanged IDs on stderr. “Written” means newly accepted source fragments whose required local persistence completed; it is neither a physical file-write count nor confirmation of cloud replication. The success line follows Save and required disposal/process-window cleanup. Persistence failures return nonzero without that receipt. --window retains its existing explicit opt-out from window release; Save must still succeed.

All source entries and strict -x / --id-exists / --patch targets are validated before mutation. Equality is against the latest fragment ignoring Modified, not against the projected state. A sparse patch matching projected values may therefore still append a fragment; distributed ordering and tombstones are preserved.

Latest Version 4.6.5

The active Python distributed-persistence implementation is now distributed as umgodi-json. It uses Inqaba for paths, files, and shared configuration; its JsonPit-compatible heritage is described above rather than hidden behind the old project name.

Without -c, jpit export Object -r AfricaStage --out-dir ./exports resolves the bare tenant name beneath the configured default cloud, matching status. Use -c <provider> to select a cloud explicitly, or -r ./AfricaStage / an absolute path for local storage. A same-named local directory does not override a bare tenant name. This also applies to report-only WWWA maintenance, audit, and grep's default target with -r.

Export exits 1 with the missing canonical .pit path on stderr when a source snapshot is absent. It emits no JSON or success receipt and leaves existing export files intact. --wwwa requires all four snapshots; a valid existing empty snapshot still exports [] successfully.

Latest release notes: coordinated RAIkeep release notes.

Previous Versions

See the umgodi-json 4.x release notes.

Key Features

  • The Persistence Fabric for AI Agents: Autonomous agents running across macOS desktop apps, backend servers, and web runtimes synchronize memory and living state across shared cloud drives without managing database servers, connection pools, or cloud credentials.
  • 0% Deviation from C# JsonPit: Reads, merges, and writes pits with identical canonical JSON serialization, UTC timestamp precision, and tombstone semantics.
  • Filesystem and configuration: Umgodi uses the Inqaba framework.
  • Cloud-Safe Filesystem Invariants (CR022): In-place sibling writes (.pit.tmp $\rightarrow$ atomic rename within the same cloud volume). Prevents cross-device link errors (EXDEV) and OneDrive mass-deletion alarms.
  • Full Distributed Lease Protocol: Implements master writer leases (Master.flag) and PID-specific process activity windows ({Machine}-{Process}-{PID}.flag) with automatic process naming from sys.argv[0].
  • Ecosystem Configuration: Seamlessly reads machine cloud paths from ~/.config/RAIkeep.json5 (with ~/.config/umgodi.json5 fallback).
  • Pure Object-Oriented Design: Rich domain entities (Pit, PitItem, PitItems) implementing standard Python protocols (MutableMapping, ContextManager).

Object-Oriented Architecture

umgodi models distributed state through rich, encapsulated domain classes implementing standard Python protocols (MutableMapping, ContextManager):

  • Pit: Living collection and coordinator of distributed leases, change files, and storage compaction.
  • PitItem: Polymorphic living entity. Emits pure sparse deltas without read-modify-write cycles (CR040).
  • PitItems: Immutable fragment stack managing value history and accurate point-in-time state projection.
  • JsonPitBase: Shared foundation for storage resolution, subscriber roles, and cloud synchronization.
  • PitMaintenanceOptions / PitMaintenanceResult: Automated reconciliation, 10-minute receipt grace periods, and flag pruning (CR021/CR022).
  • PitAudit / PitAuditEvent: Read-only durable recovery event inspection without acquiring leases or flags (CR003).

See the class diagram, its PlantUML source, the getting started guide and the API reference.

Installation & Upgrade

Python 3.12 or newer is required.

CLI with pipx

Install one environment for both commands:

pipx install "umgodi-json==4.6.5"
jpit --version
umgodi --version

To upgrade:

pipx upgrade umgodi-json

The expected outputs are jpit v4.6.5 and umgodi v4.6.5. Both commands come from the same distribution.

On Ubuntu/Debian, install pipx with sudo apt install pipx if needed. On macOS, use brew install pipx. Run pipx ensurepath and start a new shell if the commands are not on PATH. System Python may reject direct pip installation with externally-managed-environment; use pipx for the CLI.

Library in a virtual environment

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "umgodi-json==4.6.5"

Use import umgodi in Python. Existing jsonpit environments can continue using the frozen 4.6.3 release.


Quickstart

1. Cloud-First Triad (The Standard Pattern)

Given a machine configured with ~/.config/RAIkeep.json5:

from umgodi import Pit, PitItem

# Automatically resolves cloud storage (OneDriveData/AfricaStage/Person/):
with Pit.open("Person", cloud="OneDrive", root="AfricaStage") as pit:
    # Get an entity (projected state)
    sipho = pit.get("Sipho")
    if sipho:
        print(f"Sipho's current role: {sipho.get('Role')}")
        # Mutate an entity: sparse append-only mutation, auto-sets Deleted=False
        sipho.set_property({"Status": "Active", "Location": "RehearsalStage"})

    # Add a new entity
    hugh = PitItem(id="HughMasekela")
    hugh.set_property({"Genre": "Jazz", "Instruments": ["Flugelhorn", "Cornet"]})
    pit.add(hugh)

# On exit of the context manager:
# 1. Point-in-time snapshot captured
# 2. In-place sibling temporary file written (CR022 cloud-safe)
# 3. Atomically replaces Person.pit on the cloud volume
# 4. Owned process activity flag cleanly released

2. Local / Explicit Filesystem Path

For local test directories or custom scripts:

with Pit.open("/path/to/my/Person") as pit:
    for item in pit.values():
        print(item.id, item.modified)

3. Developer Companion CLI: jpit

The package installs both jpit and umgodi commands:

# Fast semantic search across one or all pits ("Pit-Grep"):
jpit grep "Adele" Person
jpit grep "Burkhardt" --root AIA

# Pipe search results directly into jq:
jpit grep "Jazz" Person --json | jq '.[].Genre'

# Inspect entity living state or full immutable history:
jpit get Person Rainer
jpit history Person Rainer

# Pipe JSON5 / JSON mutations directly into a pit:
cat update.json5 | jpit put Person
echo '{id: "AlanKay", dynabook: true}' | jpit put Person

# Set individual properties or tombstone an entity:
jpit set Person AlanKay Status "Visionary"
jpit del Person ObsoleteEntity

# Automated maintenance and dead flag pruning (100% C# pits maintain parity):
jpit maintain Activity -c OneDrive -r AIA
jpit maintain Activity -c OneDrive -r AIA --apply --prune-process-flags --older-than 01:00:00 --json
jpit maintain --wwwa -c OneDrive -r AIA --apply --prune-process-flags --older-than 7.00:00:00

# Read-only audit of durable recovery events (100% C# pits audit parity):
jpit audit Activity -c OneDrive -r AIA
jpit audit Activity -c OneDrive -r AIA --machine local --level Warning
jpit audit --wwwa -c OneDrive -r AIA --json

The Physical Structure of a Pit

A Pit is not a single file—it is a Directory Ecosystem:

Person/
├── Person.pit                     # Canonical point-in-time snapshot
├── Master.flag                    # Master writer lease ticket (Owner|Timestamp)
├── Nkosikazi-python-59346.flag    # Process activity window ({Machine}-{App}-{PID}.flag)
├── Events/                        # Immutable change streams & compaction archives
└── Changes/                       # Hashed, collision-safe change files & receipts

Autonomous Agents & Cross-Platform State

umgodi solves the distributed state dilemma for autonomous AI agents:

  1. Zero Database Infrastructure: An agent needs only a directory path on a synchronized cloud drive (e.g. OneDriveData/AIA/AgentMemory). It never requires cloud database API keys, connection pools, firewall punch-through, or hosted database servers.
  2. Auditability & Time-Travel: Because history is strictly append-only and stamped with .NET UtcTicks, every agent mutation retains full provenance. Operators or supervising agents can time-travel and inspect exact state at any millisecond.
  3. Multi-Agent Collision-Proof Coordination: Multiple agents (or desktop apps + background agents) coordinate through collision-free change files (Changes/) and opportunistic master writer leases (Master.flag), guaranteeing eventual consistency without write collisions.

Development & Testing

Cross-Library Differential Parity Battery

To ensure 100% interoperability with C# JsonPit, this repository includes a dedicated Differential Cross-Testing Suite (tests/suites/*.json5 & tests/sequence_runner.py). The test harness orchestrates bidirectional interaction between the Python runtime (jpit) and the C# CLI binary (pits):

  • Python Writes $\rightarrow$ C# Validates: Python writes .pit snapshots and sparse changes; C# pits export and pits verify assert physical byte formatting, timestamp precision, and schema invariants.
  • C# Writes $\rightarrow$ Python Validates: C# pits seed, delete-property, and maintain mutate state; Python jpit get, history, and PitStore verify projections and receipt mechanics.
  • 7 Parity Suites (41 Cross-Engine Steps): Covers persistence CRUD, CR041 clean change files, receipt grace periods, nested property tombstones, compaction/events archiving, process flag lifecycles, and split-master partition recovery.

For full suite descriptions, architecture diagrams, and certification tables, see:
👉 doc/CROSS_ENGINE_PARITY_SPECIFICATION.md

# Run the full test battery (Unit Tests + 7 Cross-Engine Parity Suites):
python3 tests/run_all.py

# Run a specific declarative parity suite directly:
python3 -m tests.sequence_runner tests/suites/01_persistence_and_crud.json5

Metadata

Release files for umgodi-json 4.6.5

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

Source distribution (sdist)

Source distribution for umgodi-json 4.6.5
File Size Uploaded Provenance Actions
umgodi_json-4.6.5.tar.gz 548.5 kB With provenance Details for umgodi_json-4.6.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for umgodi-json 4.6.5
File Interpreter ABI Platform Actions
umgodi_json-4.6.5-py3-none-any.whl Python 3 none any Details for umgodi_json-4.6.5-py3-none-any.whl

Total release size: 611.6 kB

Release files / umgodi_json-4.6.5.tar.gz

Download URL umgodi_json-4.6.5.tar.gz
Size 548.5 kB
Tags Source
SHA-256 checksum
How to use checksums
a9f3c66b8761f393ee5819198a0eab7f4c93a519c0ea918f02733a8baa98bee2
BLAKE2b-256 checksum
How to use checksums
fd26a214c27f46c49ebf4206bf070b673ea028c97ee44d79cc33bff3fc38438d
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 16, 2026.

Transparency log

Release files / umgodi_json-4.6.5-py3-none-any.whl

Download URL umgodi_json-4.6.5-py3-none-any.whl
Size 63.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f2864e429749c91f9ffef070c468c0e9f7aa5ec1645469c1424123f114bcadd3
BLAKE2b-256 checksum
How to use checksums
b7cc2a0d1df611264b43fa50cfc643a09d0b2943ca2a71e47735f585874ea557
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 16, 2026.

Transparency log

Security for umgodi-json 4.6.5

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 umgodi_json-4.6.5.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 16, 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