marivo.semantic#

marivo.semantic - Python-native semantic layer (v1.1).

Public surface:

import marivo.semantic as ms

catalog = ms.load()                # returns SemanticCatalog
catalog = ms.load(domains=['sales'])  # filter to specific domains
catalog.list().show()
catalog.list(kind="metric").show()              # all metrics across domains
catalog.list(domain="sales", kind="metric").show()  # metrics in one domain

ms.domain(name="sales", default=True)
orders = ms.entity(name="orders", datasource="warehouse", source=ms.table("orders"))
@ms.measure(entity=orders, additivity="additive", unit="USD")
def amount(orders):
    return orders.amount

revenue = ms.aggregate(name="revenue", measure=amount, agg="sum")

Declaration decorators#

`entity`	Declare an entity over a structured physical source.
`dimension`	Declare a categorical dimension whose body returns an ibis expression over its entity.
`measure`	Declare a row-level quantitative measure whose expression can be aggregated.
`metric`	Declare a metric from an ibis body.
`relationship`	Declare a join relationship between two entities.
`time_dimension`	Declare a time-aware dimension that carries grain and parsing metadata.
`domain`	Declare a semantic domain namespace inside a project file.

Aggregation & measure helpers#

`aggregate`	Declare a tier-1 simple metric: an aggregation over a measure.
`linear`	Declare a derived linear metric (no body): sum of `add` minus `subtract`.
`ratio`	Declare a derived ratio metric (no body).
`weighted_average`	Declare a derived weighted-average metric (no body).
`semi_additive`	Declare a semi-additive nature: additive off the `over` time axis, folded by `fold`.
`snapshot`	Declare daily snapshot partition versioning for an entity.
`validity`	Declare SCD2 validity interval versioning for an entity.
`join_on`	Build one relationship key pair for `ms.relationship(keys=[...])`.

Time parsing#

`datetime`	Declare an already-temporal datetime column parse.
`timestamp`	Declare an already-temporal timestamp column parse.
`strptime`	Declare a string/integer strptime parse.
`hour_prefix`	Declare an hour-only partition parse using a day prefix column.

Source builders & provenance#

`csv`	Build a structured CSV source for `ms.entity(source=...)`.
`parquet`	Build a structured parquet source for `ms.entity(source=...)`.
`table`	Build a structured table source for `ms.entity(source=...)`.
`from_sql`	Declare SQL parity provenance for a Python metric body.

Authoring handoff#

`prepare_entity`	Prepare an entity authoring brief with datasource evidence.
`prepare_dimension`	Prepare a dimension authoring brief for one entity column.
`prepare_measure`	Prepare a measure authoring brief for one entity column.
`prepare_metric`	Prepare a metric authoring brief after row-level measures are verified.
`prepare_relationship`	Prepare a relationship authoring brief with join-key probe evidence.
`prepare_time_dimension`	Prepare a time dimension authoring brief with format detection.
`prepare_domain`	Prepare a domain authoring brief from the current project.
`prepare_cross_entity_metric`	Prepare a cross-entity metric brief with relationship path evidence.
`prepare_derived_metric`	Prepare a derived metric brief from component metric refs.

Readiness & verification#

`readiness`	Run structural readiness check for the given semantic refs.
`richness`	Return a demand-ranked advisory richness report.
`verify_object`	Verify a single authored semantic object is reachable and valid.
`parity_check`	Run parity check for a metric against its source SQL.
`record_decision`	Record an authoring decision into the evidence ledger.

Refs & loading#

`ref`	Reference a semantic object by qualified `"<domain>.<object>"` string.
`make_ref`	Construct the per-kind SemanticRef subclass for `kind`.
`load`	Load a semantic project and return a browseable SemanticCatalog.

Discovery#

`help`	Print bounded agent-facing help for the semantic surface and return None.
`help_text`	Return help text as a string instead of printing it.

Ref types#

`EntityRef`	Ref returned by ms.entity().
`DimensionRef`	Ref returned by ms.dimension().
`MeasureRef`	Ref returned by ms.measure().
`MetricRef`	Ref returned by ms.aggregate(), @ms.metric(), and derived constructors.
`RelationshipRef`	Ref returned by ms.relationship().
`TimeDimensionRef`	Ref returned by ms.time_dimension().
`DomainRef`	Ref returned by ms.domain().
`SemanticRef`	Stable identity for a semantic object, shared across all layers.

Brief types#

`EntityBrief`
`DimensionBrief`
`MeasureBrief`
`MetricBrief`
`RelationshipBrief`
`TimeDimensionBrief`
`DomainBrief`
`DomainBriefSummary`
`CrossEntityMetricBrief`
`DerivedMetricBrief`
`BriefStatus`

Details types#

`EntityDetails`	Details for an entity object.
`DimensionDetails`	Details for a categorical dimension object.
`MeasureDetails`	Details for a row-level quantitative measure object.
`MetricDetails`	Represent a PEP 604 union type
`RelationshipDetails`	Details for a relationship between entities.
`TimeDimensionDetails`	Details for a time dimension object.
`DomainDetails`	Details for a domain object.
`DatasourceDetails`	Details for a datasource object.
`DerivedMetricDetails`	Details for a derived (composed) metric.
`SimpleMetricDetails`	Details for a simple (entity-backed) metric.
`SemanticObjectDetails`	Represent a PEP 604 union type

Catalog & objects#

`SemanticCatalog`	Read-only object graph over a loaded semantic project.
`SemanticObject`	Single read shape for all loaded semantic objects.
`SemanticObjectList`	Browsing result returned by catalog.list(...).
`SemanticKind`
`RegisteredMatch`
`MeasureIR`	Row-level quantitative declaration that metrics aggregate.

Sources & versioning#

`TableSource`
`FileSource`	Represent a PEP 604 union type
`DatasetSource`	Represent a PEP 604 union type
`SqlProvenance`	SQL parity provenance for a Python-authored metric body.
`SnapshotVersioning`
`ValidityVersioning`
`EntityVersioning`	Represent a PEP 604 union type
`VersioningHints`

Time-parse specs#

`DateParse`	Parse a time-dimension column as a calendar date.
`DatetimeParse`	Parse a time-dimension column as a datetime, optionally timezone-aware.
`TimestampParse`	Parse a time-dimension column as a timestamp, optionally timezone-aware.
`StrptimeParse`	Parse a time-dimension column using an explicit `strptime` format.
`HourPrefixParse`	Parse a time-dimension column from an hour-prefixed string.
`FormatCandidate`	A candidate temporal format inferred for a time-dimension column.

Readiness & assessment#

`ReadinessReport`
`ReadinessIssue`
`ReadinessInputSummary`
`RichnessReport`
`AuthoringAssessment`
`AssessmentIssue`
`AuthoringQuestion`
`ParityResult`	Result of a single metric parity check.
`VerifyResult`
`DecisionRecord`

Facts & signals#

`ComponentFact`
`DimensionValueFact`
`JoinPathFact`
`JoinKey`	One left/right relationship key pair.
`PrimaryKeyCandidate`
`DemandSignal`

AI context#

`AiContext`	Structured AI-facing context for semantic objects.
`AiContextView`

Errors#

LadderOrderError

Raised when a prepare_* call requires a prerequisite verify_object that hasn't been completed.

Submodules#

`marivo.semantic.errors`	Typed semantic errors and warnings raised across the semantic layer.
`marivo.semantic.typing`	Shared type aliases for the semantic surface.

Type aliases#

`SemanticKindInput`	Represent a PEP 604 union type
`SemanticRefInput`	Represent a PEP 604 union type