Metadata-Version: 2.4
Name: nodus-schema
Version: 0.1.0
Summary: Versioned ABI schema validation, parsing, and registry
Author: Shawn Knight
License: MIT
Project-URL: Homepage, https://github.com/Masterplanner25/nodus-schema
Project-URL: Repository, https://github.com/Masterplanner25/nodus-schema
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# nodus-schema

**Versioned ABI schema validation, parsing, and registry for Nodus AI systems.**

Validates payloads against simple-form or JSON Schema object definitions,
parses versioned surface names (`sys.v1.domain.action`), and maintains a
thread-safe `SchemaRegistry` of versioned schemas with stability tracking.
No required external dependencies — pure stdlib.

> **Note on naming:** This is the standalone `nodus-schema` package
> (`C:\dev\nodus-schema`). The nodus-lang runtime also ships an in-tree
> `nodus_schema` package (`src/nodus_schema/`) with `SyscallSpec`,
> `HandlerContract`, and `VALID_EFFECTS`. The two are distinct; check
> `python -c "import nodus_schema; print(nodus_schema.__file__)"` to confirm
> which is active.

> **Status:** v0.1.0 — prepared, not yet published.

---

## Install

```bash
pip install nodus-schema
```

---

## What it provides

| Component | Purpose |
|---|---|
| `validate_payload` | Validate a dict against a schema; returns list of error strings |
| `validate_input` / `validate_output` | Aliases for `validate_payload` |
| `parse_versioned_name` | Parse `"sys.v1.domain.action"` → `(version, action)` |
| `resolve_version` | Find best compatible version from available set |
| `is_stable_version` | True for `"v1"`, `"v2"`, etc. (not alpha/beta) |
| `SchemaEntry` | One versioned schema with stability and deprecation state |
| `SchemaRegistry` | Thread-safe registry of `SchemaEntry` objects |

---

## Schema validation

```python
from nodus_schema import validate_payload

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age":  {"type": "integer"},
    },
    "required": ["name"],
}

errors = validate_payload(schema, {"name": "Alice", "age": 30})
# [] — valid

errors = validate_payload(schema, {"age": 30})
# ["Missing required field: 'name'"]

errors = validate_payload(schema, {"name": "Alice", "age": "thirty"})
# ["Field 'age': expected type 'integer', got 'str'"]
```

### Simple-form schema

A flat `{field: type_string}` dict is also accepted:

```python
errors = validate_payload({"key": "str", "value": "any"}, {"key": "hello"})
# [] — "any" allows any type
```

Supported type strings: `string`/`str`, `integer`/`int`, `number`/`float`,
`boolean`/`bool`, `object`/`map`/`dict`, `array`/`list`, `null`/`nil`, `any`.

---

## Versioned name parsing

```python
from nodus_schema import parse_versioned_name, resolve_version, is_stable_version

version, action = parse_versioned_name("sys.v1.memory.write")
# ("v1", "memory.write")

best = resolve_version("v1", available={"v1", "v2"}, fallback=True)
# "v1"

is_stable_version("v1")      # True
is_stable_version("v1alpha1") # False
is_stable_version("v1beta2")  # False
```

---

## SchemaRegistry

```python
from nodus_schema import SchemaRegistry, SchemaEntry

registry = SchemaRegistry()
registry.register(SchemaEntry(
    name="memory.write",
    version="v1",
    input_schema={"key": "str", "value": "any"},
    output_schema={"stored": "bool"},
    stable=True,
    deprecated=False,
))

entry = registry.get("memory.write", version="v1")  # SchemaEntry | None
versions = registry.versions("memory.write")         # ["v1"]
all_entries = registry.list()                        # list[SchemaEntry]
```

---

## Design

- **No required dependencies.** Pure stdlib (`json`, `threading`, `dataclasses`).
- **Simple-form schemas.** Flat `{field: type}` dicts are normalized to JSON
  Schema objects automatically.
- **Thread-safe.** `SchemaRegistry` uses `threading.Lock`.

---

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -q
```

---

## License

MIT — see [LICENSE](LICENSE).
