uks-sdk 1.0.0

Python SDK for Universal Knowledge & Action Schema (UKS) v3.0

uks-sdk (Python)

Python SDK for building and validating Universal Knowledge & Action Schema (UKS) v3.0 packets.

pip install uks-sdk

Usage

Validate a packet

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

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

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

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
• CLI (uks-cli)
• TypeScript SDK (@uks/sdk)
• MCP Server (@uks/mcp-server)
• GitHub

License

MIT