Metadata-Version: 2.4
Name: origin-lang
Version: 0.2.0
Summary: Every value is origin, at a boundary, or contents. The runtime enforces which.
License-Expression: MIT
Project-URL: Homepage, https://github.com/knoxvilledatabase/origin
Keywords: ai,safety,boundary,inference,type-system
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Origin

Every value is origin, at a boundary, or contents. The runtime enforces which.

When your model isn't sure about something — low confidence, out of its training domain, potentially hallucinating — that uncertainty usually lives in a float field that someone might forget to check. Origin changes that.

But here's what makes it different from `try/except`: when something goes wrong, Origin doesn't throw away what the model computed. It keeps it. And when the system hits its absolute boundary — no output at all — that's a distinct sort, not just `None`.

```python
from origin_lang import Value, boundary

@boundary
class LowConfidence:
    confidence: float
    threshold: float

# Three sorts. The runtime enforces which.
match infer(text):
    case Value.Contents(diagnosis):
        treat(diagnosis)
    case Value.Boundary(LowConfidence(confidence=c), last=diagnosis):
        refer_to_specialist(diagnosis, c)
        #                   ^^^^^^^^^
        #                   still here
    case Value.Origin(reason):
        escalate(reason)
```

That's the difference between a system that says "I don't know" and a system that says "here's my full reasoning up to the point where I ran out of certainty."

| What survives a boundary | `try/except` | Origin |
|---|---|---|
| That something went wrong | yes | yes |
| Which boundary was crossed | sometimes | yes |
| What the computation last knew | **opt-in** | **guaranteed** |
| Absolute boundary vs edge | **no** | **yes** |

Zero dependencies. Pure Python. Works with any model framework.

For compile-time enforcement, see the [Rust crate](https://github.com/knoxvilledatabase/origin).

## Install

```bash
pip install origin-lang
```

## API

```python
from origin_lang import Value, boundary
from origin_lang.value import match, BoundaryError

# Define a boundary kind
@boundary
class MyBoundary:
    reason: str

# Create values — three sorts
v = Value.contents(result)                                        # safe territory
v = Value.boundary(MyBoundary(reason="uncertain"), last=partial)  # crossed edge, last value preserved
v = Value.origin(MyBoundary(reason="system failure"))             # absolute boundary, no value

# Inspect
v.is_contents    # True/False
v.is_boundary    # True/False
v.is_origin      # True/False
v.unwrap()       # returns value or raises BoundaryError
v.or_default(x)  # returns value or fallback
v.or_else(on_boundary, on_origin)  # handle each sort distinctly
v.map(fn)        # transform contents and boundary's last; origin passes through

# or_else — handle each sort without a full match
result = v.or_else(
    lambda reason, last: f"uncertain ({reason.confidence:.0%}): {last}",
    lambda reason: f"failed: {reason}",
)

# Pattern match (Python 3.10+)
m = match(v)
match m:
    case Value.Contents(value):
        use(value)
    case Value.Boundary(reason, last=residual):
        handle(reason, residual)
    case Value.Origin(reason):
        escalate(reason)
```

## Where This Came From

Origin is formally verified in the [two-sorted arithmetic](https://github.com/knoxvilledatabase/two-sorted-arithmetic) project — 508 Lean 4 theorems proving that three sorts are necessary and sufficient. The [Rust crate](https://github.com/knoxvilledatabase/origin) provides compile-time enforcement. This Python package provides runtime enforcement with the same vocabulary.

Three sorts. The `last` field is always preserved in Boundary. Origin carries only the reason. Contents carries the value.

Note: the Rust crate includes `Chain` for reasoning traces (showing every step before a boundary was hit). The Python package does not yet implement `Chain` — pattern matching and `or_else` are the primary tools for handling boundaries in Python.

Zero external dependencies. Uses only `dataclasses` from the standard library.
