uks-sdk 1.0.0__tar.gz

uks_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,137 @@
+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

uks_sdk-1.0.0/README_PYPI.md

@@ -0,0 +1,111 @@
+# 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

uks_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uks-sdk"
+version = "1.0.0"
+description = "Python SDK for Universal Knowledge & Action Schema (UKS) v3.0"
+license = { text = "MIT" }
+readme = "README_PYPI.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.7",
+    "jsonschema>=4.22",
+]
+keywords = ["uks", "universal-knowledge-schema", "pydantic", "json-schema", "knowledge", "ai-agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/Vybecode-LTD/SaberTools/tree/main/packages/uks-sdk-py#readme"
+"Specification" = "https://github.com/Vybecode-LTD/SaberTools/tree/main/spec"
+"Source" = "https://github.com/Vybecode-LTD/SaberTools"
+"Bug Tracker" = "https://github.com/Vybecode-LTD/SaberTools/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["uks_sdk*"]
+
+[tool.setuptools.package-data]
+uks_sdk = ["schema/*.json"]

uks_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uks_sdk-1.0.0/tests/test_conformance.py

@@ -0,0 +1,109 @@
+"""
+Cross-implementation conformance parity harness for uks-sdk (Python).
+Runs validate_file() over the canonical spec corpus (examples + valid/ + invalid/)
+so the Python SDK is proven to agree with the CLI and the TypeScript SDK.
+
+Run from anywhere:  python packages/uks-sdk-py/tests/test_conformance.py
+Exits non-zero on any mismatch.
+"""
+import pathlib
+import sys
+
+# Make the local uks_sdk importable without installing.
+_PKG_ROOT = pathlib.Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(_PKG_ROOT))
+
+from uks_sdk import validate, validate_file, UKSPacket  # noqa: E402
+
+_REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+_SPEC = _REPO_ROOT / "spec"
+
+passed = 0
+failed = 0
+
+
+def _check(directory: pathlib.Path, want_valid: bool, label: str) -> None:
+    global passed, failed
+    print(f"{label}:")
+    for f in sorted(directory.glob("*.json")):
+        result = validate_file(f)
+        ok = result.valid == want_valid
+        if ok:
+            print(f"  OK  {f.name}")
+            passed += 1
+        else:
+            why = (
+                f"expected valid, got: {result.errors[0].path} {result.errors[0].message}"
+                if want_valid else "expected invalid but passed"
+            )
+            print(f"  XX  {f.name} — {why}")
+            failed += 1
+
+
+def _check_level_mismatch(directory: pathlib.Path, label: str) -> None:
+    """Schema-valid packets whose declared conformance_level != inferred level:
+    must be valid AND flag level_match=False (parity guard for level inference)."""
+    global passed, failed
+    print(f"{label}:")
+    for f in sorted(directory.glob("*.json")):
+        result = validate_file(f)
+        if result.valid is True and result.level_match is False:
+            print(f"  OK  {f.name} (declared {result.declared_level} != inferred {result.inferred_level})")
+            passed += 1
+        else:
+            print(f"  XX  {f.name} — expected valid + level_match=False, "
+                  f"got valid={result.valid} level_match={result.level_match}")
+            failed += 1
+
+
+def _check_model_parity() -> None:
+    """SDK-2: the Pydantic model must agree with the JSON Schema. It must NOT
+    accept a root ``description``/``tags`` (the schema root is
+    additionalProperties:false and defines neither), and a valid model must
+    round-trip to a schema-valid dict."""
+    global passed, failed
+    print("Model/schema parity (SDK-2):")
+
+    minimal_source = dict(id="src_001", title="t", source_type="meta_analysis",
+                          credibility_score=9, evidence_grade="high",
+                          clinical_status="validated")
+    base = dict(packet_id="pkt_model", conformance_level="L1",
+                created_at="2026-06-18T00:00:00Z", topic={"title": "t"},
+                sources=[minimal_source])
+
+    # 1. A root field the JSON Schema forbids must be rejected by the model too.
+    rejected = False
+    try:
+        UKSPacket(**base, description="not a root field")
+    except Exception:
+        rejected = True
+
+    # 2. A valid model round-trips to a schema-valid dict.
+    pkt = UKSPacket(**base)
+    rt = validate(pkt.model_dump(mode="json", by_alias=True, exclude_none=True))
+
+    if rejected and rt.valid:
+        print("  OK  model rejects root description; valid model round-trips schema-valid")
+        passed += 1
+    else:
+        why = f"rejected_root_description={rejected} roundtrip_valid={rt.valid}"
+        if not rt.valid:
+            why += f" errors={[e.message for e in rt.errors]}"
+        print(f"  XX  model/schema drift — {why}")
+        failed += 1
+
+
+def main() -> int:
+    print("\nuks-sdk conformance parity (Python implementation)\n")
+    _check(_SPEC / "examples", True, "Canonical examples (must pass)")
+    _check(_SPEC / "tests" / "valid", True, "Valid packets (must pass)")
+    _check(_SPEC / "tests" / "invalid", False, "Invalid packets (must fail)")
+    _check_level_mismatch(_SPEC / "tests" / "level-mismatch", "Level mismatch (valid but declared != inferred)")
+    _check_model_parity()
+    total = passed + failed
+    print(f"\n{total} checks: {passed} passed, {failed} failed\n")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

uks_sdk-1.0.0/uks_sdk/__init__.py

@@ -0,0 +1,73 @@
+"""
+uks-sdk — Python SDK for Universal Knowledge & Action Schema v3.0
+
+Usage::
+
+    from uks_sdk import UKSPacket, Topic, Source, EvidenceGrade, ClinicalStatus, validate
+
+    source = Source(
+        id='src_001',
+        title='Vitamin D meta-analysis',
+        source_type='meta_analysis',
+        credibility_score=9,
+        evidence_grade=EvidenceGrade.high,
+        clinical_status=ClinicalStatus.validated,
+        license_label='CC BY 4.0',
+    )
+
+    packet = UKSPacket(
+        packet_id='pkt_001',
+        schema_version='3.0',
+        conformance_level='L1',
+        created_at='2026-06-16T00:00:00Z',
+        topic=Topic(title='Vitamin D supplementation'),
+        sources=[source],
+    )
+
+    result = validate(packet.model_dump(by_alias=True, exclude_none=True))
+    assert result.valid
+
+"""
+
+from .types import (
+    UKSPacket,
+    Topic,
+    Source,
+    DataContract,
+    ScrapeTarget,
+    ExtractionRule,
+    Directive,
+    Action,
+    ActionStep,
+    Trigger,
+    AgentInstructions,
+    ConformanceLevel,
+    SourceDomain,
+    EvidenceGrade,
+    ClinicalStatus,
+    SourceType,
+)
+from .validate import validate, validate_file, ValidationResult, ValidationError
+
+__all__ = [
+    'UKSPacket',
+    'Topic',
+    'Source',
+    'DataContract',
+    'ScrapeTarget',
+    'ExtractionRule',
+    'Directive',
+    'Action',
+    'ActionStep',
+    'Trigger',
+    'AgentInstructions',
+    'ConformanceLevel',
+    'SourceDomain',
+    'EvidenceGrade',
+    'ClinicalStatus',
+    'SourceType',
+    'validate',
+    'validate_file',
+    'ValidationResult',
+    'ValidationError',
+]