Metadata-Version: 2.4
Name: slimschema
Version: 0.0.1.dev0
Summary: Token-efficient schema language for LLMs with fast Zig backend
Author: BotAssembly
License: MIT
Project-URL: Homepage, https://github.com/botassembly/slimschema
Project-URL: Repository, https://github.com/botassembly/slimschema
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.20.0
Provides-Extra: pydantic
Requires-Dist: pydantic>=2.0.0; extra == "pydantic"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: all
Requires-Dist: slimschema[pydantic]; extra == "all"

# SlimSchema

SlimSchema is a schema language optimized for LLM token efficiency that converts between **YAML**, **Pydantic**, and **msgspec**.

## Core Features

*   **Token Efficient:** Compressed syntax (`age: 18..120`) saves context window and costs.
*   **Deep Validation:** Recursive validation for nested objects and dictionaries.
*   **Universal Bridge:** Convert between formats (Pydantic ↔ YAML ↔ msgspec).

## Quick Start

```bash
uv pip install slimschema
pip install slimschema
```

### Example

Define a schema with nested types and defaults, validate data, and get a validated Python object.

```python
from slimschema import to_data, to_pydantic

# 1. Define a compact schema (with nested defaults!)
schema = """
user:
  name: str{3..50}
  role: admin | user | guest = "guest"
  settings:
    theme: str = "dark"
    notifications: bool = true
"""

# 2. Validate JSON data (string or dict/list)
# Input missing 'settings' -> defaults apply automatically
data, error = to_data('{"user": {"name": "Alice"}}', schema)

print(data)
# {
#   "user": {
#     "name": "Alice",
#     "role": "guest",
#     "settings": {"theme": "dark", "notifications": True}
#   }
# }

# 3. Convert to Pydantic for your app
UserModel = to_pydantic(schema)
instance = UserModel(**data)
print(instance.user.settings.theme) # "dark"
```

### Full Spec

```yaml
# Primitives
field: str | int | float | bool | obj

# Default generators
id: str = uuid                 # UUID v4 string
id_v7: str = uuid7             # UUID v7 (time-ordered)
id_ulid: str = ulid            # ULID (sortable)
id_xid: str = xid              # XID (compact, sortable)
id_nano: str = nanoid          # NanoID (URL-safe)
created: datetime = now        # Current datetime
day: date = today              # Current date
ts: int = epoch                # Unix timestamp (seconds)

# Format types
email: email
website: url
birthday: date
timestamp: datetime

# Collections
items: list[str]
tags: set[str]
coords: tuple[float, float]

# Constraints
name: str{3..50}        # Length 3-50
age: 18..120            # Range
code: /^[A-Z]{3}$/      # Regex

# Enums and Unions
status: active | pending | done    # Enum (Literal)
value: str | int                   # Union

# Typed dictionaries
scores: dict[str, int]             # Key-value types

# Inline objects
user: {name: str, age: int, email?: str}

# Optional vs Nullable
?optional_field: str    # Can omit field entirely
nullable_field: str?    # Field required, value can be null
?both: str?             # Optional AND nullable
```

### Default Syntax

```yaml
count: int = 0
name: str = "default"
items: list = []
created: str = now              # Current datetime
id: str = uuid                  # UUID v4
id2: str = uuid7                # UUID v7 (time-ordered)
id3: str = ulid                 # ULID (sortable)
id4: str = xid                  # XID (compact)
id5: str = nanoid               # NanoID (URL-safe)
ts: int = epoch                 # Unix timestamp (seconds)
```

### API Functions

```python
from slimschema import (
    parse_slimschema,  # YAML string → Schema IR
    to_schema,         # Any input → Schema IR
    to_data,           # JSON string/dict + schema → (data, error)
    to_pydantic,       # Schema → Pydantic model class
    to_msgspec,        # Schema → msgspec Struct class
    to_yaml,           # Schema → YAML string
    SchemaParseError,  # Exception for parse errors
)
```

## Documentation

**Guides**
*   [Syntax Guide](docs/guide_syntax.md): Primitives, constraints, and inline objects.
*   [Validation Guide](docs/guide_validation.md): How `to_data` validates and reports errors.
*   [Defaults Guide](docs/guide_defaults.md): Handling partial data with scalar and nested defaults.

**Integrations**
*   [Pydantic](docs/integration_pydantic.md): Round-trip conversion and nested models.
*   [msgspec](docs/integration_msgspec.md): High-performance validation structs.

**Reference**
*   [API Reference](docs/reference_api.md): Complete function signatures.
*   [Error Handling](docs/reference_errors.md): Validation and parsing errors.
*   [FAQ](docs/reference_faq.md): Common questions.

## API Reference

*   `to_data(data, schema)`: Validate JSON string or dict/list against schema.
*   `to_schema(obj)`: Convert Pydantic/msgspec/YAML to SlimSchema IR.
*   `to_yaml(schema)`: Convert Schema to compact YAML string.
*   `to_pydantic(schema)`: Generate Pydantic models.
*   `to_msgspec(schema)`: Generate msgspec structs.

## License

MIT
