Metadata-Version: 2.4
Name: owhile
Version: 0.2.0
Summary: Owhile — interactive experiences you step into, for a little while.
Author: Owhile
License: Proprietary
Project-URL: Homepage, https://owhile.vercel.app
Project-URL: Documentation, https://owhile.vercel.app/llms.txt
Project-URL: Bug Tracker, https://github.com/Owhile/owhile-web/issues
Keywords: content,gates,safety,authoring,validation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Dynamic: license-file

# owhile

**Profile-driven content gates.** It checks whether a body of content is safe for the audience you
declared it for. Every audience rule lives in a JSON profile; the gate code never changes. The same
code gates a pre-reader safeguarding bank and an adult compliance bank without a line differing —
only the profile does.

**What this is not.** It is not a game engine and not a library of playable mechanics. A *mechanic*
here is a declaration — a verb name, a map of what each field is for, and structural rules — not
code you can run. Declaring your own needs no permission and the gates will enforce it, but nothing
in this package renders or plays anything. Gating a mechanic and playing one are different problems
and only the first is solved.

Built for [Owhile](https://owhile.vercel.app), where creators publish interactive experiences.

## Install

```bash
pip install owhile
owhile --version
```

## The shape of it

```bash
owhile init                                   # write a starting profile
owhile profile check                          # is it valid, and could it be listed?
owhile template --mechanic reflect --out sheet.csv
owhile build --sheet sheet.csv --out bank.ndjson
owhile check --report report.json
```

The runbook, written to be handed to a coding agent, is at
**https://owhile.vercel.app/creators/start.md**.

## What it actually does

Five gates run over every item, and each reports `pass`, `fail` or `could_not_run` — so a gate that
could not run is never mistaken for one that passed:

- **role_totality** — every scalar in an item has a declared role. A field nobody declared is a
  finding, not a shrug.
- **invariants** — your structural rules, declared per mechanic and validated at load, so a rule the
  gate cannot execute is refused before any content is read rather than crashing once per item.
- **permissions** — an audience may only use the mechanics it permits.
- **budgets** — reading length, counted in grapheme clusters rather than code points. A cap
  calibrated on English is a much harsher rule in Devanagari.
- **resources** — a cited helpline or policy reference must match your registry, and a correct
  citation is matched at its own full length before any hunt for a wrong one.

The report binds its verdict to a digest of the content **and** to a digest of the code that
produced it, so a verdict cannot outlive either.

## Declared, never inferred

The design rule the whole thing turns on. Meaning is declared in your profile and never guessed from
prose: which side of a choice is affirming, which text is a myth being struck rather than an
assertion, how old your youngest reader is. Earlier code inferred the affirming side by
regex-matching an English label and painted the negative side green on sixteen live consent
scenarios. A declared field cannot be wrong that way — it can only be absent, and absence blocks.

`min_age` has no default for the same reason. A profile without one is valid and its content gates
clean; it is *listing* that is blocked. Silence is never read as adult.

## Reporting a problem

https://github.com/Owhile/owhile-web/issues

**Do not paste the output of `owhile check`, and do not attach files.** A blocked run prints your
item text verbatim, and a public issue cannot be un-published. Describe it in words — rule names
and counts are fine, finding text is not. Anything that cannot be said in public has a private
route linked from that page.

## Status

**0.1.1, and honest about it.** The gates, the profile loader, the authoring loop and the report
format are built and tested — 217 tests, mutation-tested, and proven across a 29,365-item corpus in
two opposite audiences. The `owhile` command wrapping them is new in this release and has had far
less use than the code underneath it. Listing on Owhile is not open yet: the eligibility rule and
the digest binding are decided and enforced, and there is no submission path at all.

Known limits are documented rather than hidden, at
**https://owhile.vercel.app/creators/gates.md**.

## Licence

Proprietary. All rights reserved.
