Metadata-Version: 2.4
Name: uks-sdk
Version: 1.0.0
Summary: Python SDK for Universal Knowledge & Action Schema (UKS) v3.0
License: MIT
Project-URL: Homepage, https://github.com/Vybecode-LTD/SaberTools/tree/main/packages/uks-sdk-py#readme
Project-URL: Specification, https://github.com/Vybecode-LTD/SaberTools/tree/main/spec
Project-URL: Source, https://github.com/Vybecode-LTD/SaberTools
Project-URL: Bug Tracker, https://github.com/Vybecode-LTD/SaberTools/issues
Keywords: uks,universal-knowledge-schema,pydantic,json-schema,knowledge,ai-agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.7
Requires-Dist: jsonschema>=4.22

# uks-sdk (Python)

Python SDK for building and validating
[Universal Knowledge & Action Schema (UKS)](https://uks.dev) v3.0 packets.

```
pip install uks-sdk
```

## Usage

### Validate a packet

```python
from uks_sdk import validate, validate_file

# From a dict
result = validate(packet_dict)
print(result.valid, result.inferred_level, result.level_match)
if not result.valid:
    for err in result.errors:
        print(err)

# From a file
result = validate_file("my-packet.uks.json")
```

### Build a packet with Pydantic models

```python
from uks_sdk import UKSPacket, Source, Topic

packet = UKSPacket(
    packet_id="uks-omega3-v1",
    schema_version="3.0",
    conformance_level="L1",
    created_at="2026-06-16T00:00:00Z",
    topic=Topic(title="Omega-3 Fatty Acids"),   # topic is an object, not a bare string
    sources=[
        Source(
            id="src_001",
            title="Effect of EPA and DHA on cardiovascular risk",
            source_type="research_paper",
            credibility_score=9,
            evidence_grade="high",
            clinical_status="validated",
            doi="10.1000/example",
            license_label="CC BY 4.0",
            rights_url="https://creativecommons.org/licenses/by/4.0/",
        )
    ],
)

import json
# by_alias=True so `_extensions` (not `extensions`) is emitted
print(json.dumps(packet.model_dump(by_alias=True, exclude_none=True), indent=2))
```

### Validate a built packet

```python
result = validate(packet.model_dump(by_alias=True, exclude_none=True))
assert result.valid
```

## Types

All UKS v3.0 types are available as Pydantic v2 models:

| Model | Description |
|-------|-------------|
| `UKSPacket` | Root packet object |
| `Source` | Research source |
| `DataContract` | Layer A contract |
| `ScrapeTarget` | Layer B acquisition target |
| `ExtractionRule` | Layer C parsing rule |
| `Directive` | Layer D processing rule |
| `Action` | Layer E action |
| `ActionStep` | Individual action step |
| `AgentInstructions` | Agent behavior configuration |
| `KnowledgeNode` | Entity in the knowledge graph |

## Evidence Grades

```python
from uks_sdk import EvidenceGrade

EvidenceGrade.HIGH       # "high"   — meta-analyses of RCTs
EvidenceGrade.MODERATE   # "moderate" — individual RCTs
EvidenceGrade.LOW        # "low"   — observational studies
EvidenceGrade.VERY_LOW   # "very_low" — expert opinion
EvidenceGrade.NA         # "n_a"   — datasets, non-clinical
```

## Requirements

- Python 3.10+
- pydantic >= 2.7
- jsonschema >= 4.22

## Links

- [Specification](https://uks.dev/spec/)
- [CLI (uks-cli)](https://www.npmjs.com/package/uks-cli)
- [TypeScript SDK (@uks/sdk)](https://www.npmjs.com/package/@uks/sdk)
- [MCP Server (@uks/mcp-server)](https://www.npmjs.com/package/@uks/mcp-server)
- [GitHub](https://github.com/UKS-Standard/uks-spec)

## License

MIT
