Metadata-Version: 2.4
Name: refpot
Version: 0.1.1
Summary: Experimental embedded native key-value database engine
Author: Tugrul Guner
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/tugrulguner/refpot
Project-URL: Repository, https://github.com/tugrulguner/refpot
Project-URL: Issues, https://github.com/tugrulguner/refpot/issues
Project-URL: Changelog, https://github.com/tugrulguner/refpot/blob/main/CHANGELOG.md
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown

# refpot

<p align="center">
  <img src="docs/assets/refpot-lockup.png" alt="RefPot — embedded, relational, simple" width="600">
</p>

<p align="center">Part of <a href="https://modepot.io/">ModePot</a>. &nbsp; <a href="https://refpot.modepot.io/">Project website</a> &nbsp; <a href="https://tugrul.modepot.io/">Created by Tugrul Guner</a></p>

<p align="center">
  <strong>A custom embedded database preview for Python.</strong>
</p>

<p align="center">
  RefPot is an experimental alpha: a native C++ redo-and-checkpoint engine with Python CRUD and explicit transactions. Version 0.1.1 is the first release; until its public-index installation is verified, use the release-candidate artifact rather than claiming it is available from PyPI.
</p>

<p align="center">
  <a href="https://github.com/tugrulguner/refpot/actions/workflows/ci.yml"><img src="https://github.com/tugrulguner/refpot/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <img src="https://img.shields.io/badge/Python-3.11--3.14-3776AB?logo=python&amp;logoColor=white" alt="Python 3.11 through 3.14">
  <img src="https://img.shields.io/badge/Status-Experimental%20alpha-49515e" alt="Experimental alpha">
  <a href="https://github.com/tugrulguner/refpot/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
  <a href="https://discord.gg/u3AANZr6RG"><img src="https://img.shields.io/badge/Discord-Join%20ModePot-5865F2?logo=discord&amp;logoColor=white" alt="Join the ModePot Discord"></a>
  <a href="https://github.com/tugrulguner/refpot"><img src="https://img.shields.io/github/stars/tugrulguner/refpot?style=flat" alt="GitHub stars"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick start</a> ·
  <a href="#why-refpot">Why RefPot</a> ·
  <a href="#package-contract">Package contract</a> ·
  <a href="https://refpot.modepot.io/">Documentation</a> ·
  <a href="https://refpot.modepot.io/package-contract/">Deep reference</a> ·
  <a href="#examples">Examples</a> ·
  <a href="https://github.com/tugrulguner/refpot/blob/main/skills/refpot-database/SKILL.md">Agent skill</a> ·
  <a href="#community">Community</a> ·
  <a href="#contributing">Contributing</a>
</p>

<p align="center">
  <img src="docs/assets/refpot-execution.png" alt="Planned RefPot architecture, not shipped: direct SQL and a Python ORM's structured operations share one execution core, validation, constraints, transaction guarantees, storage, and recovery" width="960">
</p>

> [!IMPORTANT]
> Version 0.1.1 is the first experimental alpha release candidate. It is not a PyPI release yet; install from the locally built artifact until publication is independently verified. Package and platform qualification remain limited. No general performance claim or production durability guarantee is made.

## Why RefPot

RefPot is an early custom embedded database engine: a native C++ redo-and-checkpoint core exposed through a small Python `Database` / `Row` API. The package preview already supports fixed-schema CRUD and explicit transactions; it is not merely a research design. SQL and ORM are future design direction, not shipped interfaces.

## Quick start

Requires Python 3.11–3.14. Once public-index availability is verified, install the experimental alpha with `python -m pip install refpot==0.1.1`. Matching prebuilt wheels target Linux x86_64 and macOS arm64; other source builds require a C++17 toolchain. Before publication, build the release candidate from the repository root:

```sh
uv pip install .
python - <<'PY'
from pathlib import Path
from tempfile import TemporaryDirectory

from refpot import Database, Row

with TemporaryDirectory(prefix="refpot-quickstart-") as directory:
    path = Path(directory) / "example.rp"  # The parent directory must exist.
    with Database(path) as db:
        db.insert(1, 42, "answer")
        db.update(1, value=43)
        assert db.get(1) == Row(1, 43, "answer")
        with db.transaction():
            db.insert(2, 99)
        try:
            with db.transaction():
                db.update(1, value=100)
                raise RuntimeError("roll back this transaction")
        except RuntimeError:
            pass
        assert db.get(1) == Row(1, 43, "answer")
        db.delete(2)
    with Database(path) as db:
        assert db.get(1) == Row(1, 43, "answer")
        print(db.get(1))
PY
```

The example demonstrates CRUD, transaction commit and rollback, and persisted state after close/reopen. No output is prescribed here; run it to see the actual `Row` representation. This is a local source build, not a released install path. Also run the shipped [CRUD example](examples/crud.py) and [transaction example](examples/transactions.py).

## Package contract

The database starts empty. Keys and integer values are signed 64-bit integers; text is UTF-8 limited to 31 encoded bytes. The database path names a **file, not a directory**, and its parent directory must already exist. One process exclusively owns each database; only its creating thread may use the handle.

The native engine uses versioned snapshots and a WAL. Snapshot and WAL recovery are each bounded to 64 MiB. Incomplete unacknowledged tails are discarded; complete transactions with both copies corrupt are rejected; uncertain writes poison the writer. These implementation details are not broad recovery qualification or a physical power-loss guarantee. Concurrent readers, multiwriter use, Windows, existing-format compatibility, SQL and ORM are unsupported. See the full [package contract](docs/package-contract.md) and [package recommendation](docs/package-recommendation.md).

## Current package architecture

<p align="center"><a href="docs/assets/refpot-package.svg"><img src="docs/assets/refpot-package.png" alt="Recorded pre-release implementation architecture: Python Database and Row use a native C++ engine; transactions synchronize duplicated checksummed redo before memory publication; checkpoint snapshot sync, rename and directory sync precede log truncation. Limits and qualifications are listed in the accessible text above." width="960"></a></p>

[Open the full-size editable SVG](docs/assets/refpot-package.svg) · [Detailed package contract](docs/package-contract.md)

Mutation and diff-scan paths copy maps; package performance is unqualified and this preview is not presented as benchmark-fast.

## Examples

The standalone [CRUD example](examples/crud.py) exercises insert, update, delete, context-managed close, and reopen. The [transaction example](examples/transactions.py) demonstrates read-your-writes, commit, rollback, checkpoint, and reopen. Run them after installation:

```sh
python examples/crud.py
python examples/transactions.py
```

The full task-first docs live at [RefPot documentation](https://refpot.modepot.io/) with [package quick start](https://refpot.modepot.io/package/), [package reference](https://refpot.modepot.io/package-contract/), [status and next steps](https://refpot.modepot.io/status/), and [design direction](https://refpot.modepot.io/design/).

## Retained benchmark findings

<p align="center"><img src="docs/assets/refpot-benchmark.png" alt="Audited random-update benchmark: both campaigns pass the scoped service/setup/p99 matrix; reopen with full-state validation loses every cell" width="960"></p>

[Detailed findings, raw evidence and reproduction](benchmarks/random-updates/README.md) ·
[Full-size chart](docs/assets/refpot-benchmark.png) ·
[Next package recommendation](docs/package-recommendation.md)

The experimental findings are separate from package performance. The 3.04–5.95× result applies only to the historical update harness; it is not a package claim. The historical reopen result remains 16/16 losses. No performance ratio is asserted for this package.

## Planned design direction

The preserved [planned architecture visual above](#refpot) shows a future SQL/ORM direction, not this preview. Neither SQL nor ORM is implemented.

- **Engine first.** Establish correctness and performance before building the ORM.
- **One semantic boundary.** Direct operations must not bypass validation or constraints.
- **Explicit guarantees.** Internal plan selection must not silently weaken durability,
  isolation, transaction boundaries, or result semantics.
- **Bounded maintenance.** Include checkpointing, reclamation, and recovery debt in design
  and measurement, rather than hiding them outside favorable timings.
- **Simple public usage.** Keep storage layout, encoding, and routing choices private
  unless a user genuinely needs an operational control.

Language, storage format, index structure, isolation model, and SQL compatibility scope
remain decisions to earn through coherent experiments. A native-language rewrite alone
is not a differentiator. No SQLite SQL, file-format, or C API compatibility is promised.

## Performance target

**At least 2× improvement over SQLite is an acceptance target, not an achieved package guarantee.**

Before claiming it, define and publish a workload matrix, then retain every passing and
failing cell. Compare equivalent operations, returned values, transaction boundaries,
constraints, and durability acknowledgments against prepared SQLite and its best-tested
configuration for each workload. Package performance remains unqualified.

## Community

Join the [ModePot Discord](https://discord.gg/u3AANZr6RG) for design discussions,
implementation questions, early ideas, and database use cases across the family.
Use [GitHub Issues](https://github.com/tugrulguner/refpot/issues) for scoped proposals
and reproducible findings. The experimental alpha is not yet broadly qualified.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and contribution workflow. Repository-local coding-agent guidance is in [AGENTS.md](https://github.com/tugrulguner/refpot/blob/main/AGENTS.md), with the installable [RefPot database skill](https://github.com/tugrulguner/refpot/blob/main/skills/refpot-database/SKILL.md) for consumer-facing API boundaries. The first useful work is helping define a small, testable engine contract and qualification
matrix. Correctness cases, crash and I/O-failure scenarios, reproducible benchmark methods,
and low-ceremony usage designs are more useful now than a broad speculative API.

Discuss substantial architecture or public-contract changes in
[GitHub Issues](https://github.com/tugrulguner/refpot/issues) before implementing them.
Do not introduce a SQLite wrapper as the engine, publish invented benchmark output, or
present research prototypes as production capabilities.

The logo source is [SVG](docs/assets/refpot-lockup.svg); the README uses its
[PNG rendering](docs/assets/refpot-lockup.png).

## License

RefPot is distributed under the [MIT License](LICENSE).

See [CHANGELOG.md](CHANGELOG.md) for changes and [release guidance](docs/releasing.md) for release policy.
