Python SDK
The Python SDK (gemara-python) provides generated Pydantic v2 models for Gemara v1 documents. It enables loading, validating, manipulating, and inspecting Gemara JSON and YAML files with full static type hints and runtime validation. Types are generated from CUE schemas, ensuring consistency with the Gemara core specification.
| Python Repository → | PyPI Package → | Issue Tracker → |
Installation
gemara-python requires Python 3.11+ (supports Python 3.11, 3.12, 3.13, and 3.14).
pip install gemara-python
Or using uv:
uv add gemara-python
Loading Documents
The SDK supports both YAML and JSON document formats (YAML is handled as a superset of JSON). You can load documents either via dynamic dispatch or direct concrete type loading.
Dynamic Dispatch Loading (load / loads)
When working with arbitrary Gemara documents where the type is determined at runtime by the document’s metadata.type discriminator, use load (for files) or loads (for strings/bytes):
from gemara.v1 import ControlCatalog, Lexicon, load
# Automatically inspects metadata.type and parses into the appropriate model
doc = load("catalog.yaml")
# Pattern match or inspect the concrete model
match doc:
case ControlCatalog():
print(f"Loaded Control Catalog with {len(doc.controls or [])} controls.")
case Lexicon():
print(f"Loaded Lexicon with {len(doc.terms)} terms.")
load(source): Accepts a file path (str,Path) or an open file object (IO[str],IO[bytes]).loads(text): Accepts raw text (str) or UTF-8 encoded bytes (bytes,bytearray,memoryview) containing JSON or YAML.
Direct Concrete Type Loading (from_file / from_text)
When the document kind is known in advance, load directly through the model class to receive that concrete type without dynamic dispatch:
from gemara.v1 import GuidanceCatalog
# Directly validates and loads guidance.yaml into a GuidanceCatalog instance
guidance = GuidanceCatalog.from_file("guidance.yaml")
print(f"Guidance ID: {guidance.metadata.id}")
Model.from_file(source): Reads and parses a file directly into the model.Model.from_text(text): Parses a JSON/YAML string or bytes directly into the model.
Core Concepts & Type Hierarchy
Union Return Type
Functions load() and loads() return GemaraDocument, a TypeAlias union representing all 13 supported Gemara v1 document types:
- Catalogs:
CapabilityCatalog,ControlCatalog,GuidanceCatalog,PrincipleCatalog,RiskCatalog,ThreatCatalog,VectorCatalog - Logs:
AuditLog,EnforcementLog,EvaluationLog - Other:
Lexicon,MappingDocument,Policy
Category Narrowing
All catalog documents inherit from Catalog and all log documents inherit from Log:
from gemara.v1 import Catalog, Log, load
doc = load("sample.yaml")
if isinstance(doc, Catalog):
print("This is a Gemara Catalog.")
elif isinstance(doc, Log):
print("This is a Gemara Log.")
Error Handling
All custom exceptions defined by the SDK inherit from GemaraError. Note that schema validation failures raise Pydantic’s ValidationError, and filesystem issues raise standard OSError (neither is a GemaraError subclass), so catch them explicitly as shown below:
from gemara.v1 import GemaraError, UnknownDocumentTypeError, load
from pydantic import ValidationError
try:
doc = load("document.yaml")
except UnknownDocumentTypeError as e:
# metadata.type was missing or unrecognized
print(f"Unsupported document type: {e}")
except ValidationError as e:
# Document schema validation failed
print(f"Schema validation error: {e}")
except GemaraError as e:
# Non-UTF-8 bytes, unparseable YAML/JSON, or non-mapping input
print(f"Gemara parsing error: {e}")
except OSError as e:
# File I/O issues
print(f"Filesystem error: {e}")
Schema Compatibility & Limitations
- Additive Changes: Within Gemara v1, changes are backwards compatible. The models read any v1.x document. Unrecognized properties are accepted and ignored. Note that misspelled field names (e.g.
contrlsinstead ofcontrols) will load without an error and be dropped silently. - Structural Validation vs. CUE:
gemara-pythonperforms structural schema validation (required fields, enums, regex patterns, length bounds). For deep cross-field relational validation, rejection of unrecognized or misspelled properties, or referential integrity enforced via CUE comprehensions, validate usingcue vetalongside the core Gemara CUE schemas.
Useful Exports
SCHEMA_VERSION: The Gemara schema version used to generate the models (e.g."1.5.0").__version__: The installedgemara-pythonlibrary version.DOCUMENT_TYPES: Dictionary mappingmetadata.typestring values to model classes.
Relationship to Other Components
The Model
Provides the conceptual foundation. Python SDK types correspond to elements in the model.
The Schemas
Python SDK types are generated from the CUE schemas, ensuring consistency between validation and programmatic access. The schema version supported is exposed as gemara.v1.SCHEMA_VERSION.