Skip to content
Analysis, posture & rules

Analysis, posture & rules

Statistics, estate posture and business-rule reconciliation.

  • AnalysisService runs statistical methods on data you send: forecasting, lag features, clustering, causal intervention and descriptive statistics.
  • PostureService serves the data-maturity picture that a fetch produced, maps the connected estate into a domain graph, and runs causal interventions over estate columns.
  • RulesService serves the business rules the reconciliation agent derived and stores the operator’s enforcement policy for each.

Summary

ServiceRPCKindPurpose
AnalysisServiceAnalyzeTimeSeriesUnaryBacktest-selected forecast, stationarity and anomalies
AnalysisServiceAnalyzeFeatureUnarySignificant autocorrelation lags
AnalysisServiceClusterRefinementUnaryDensity clustering of embedding vectors
AnalysisServiceAnalyzeCausalUnaryDo-intervention over a graph you state
AnalysisServiceInferBayesianUnaryBayesian posterior (no network defined)
AnalysisServiceAnalyzeDescriptiveStatsUnaryMean, median, variance, skewness, kurtosis
AnalysisServiceClassifyESGRelevanceUnaryESG relevance score for text
PostureServiceGetHealthScoreUnaryDomain health, assessments, measures and contexts
PostureServiceBuildDomainGraphUnaryMap the connected estate into domains
PostureServiceAnalyzeEstateCausalUnaryDo-intervention over estate columns
PostureServiceListIncidentsUnaryData-maturity assessments
PostureServiceGetContextUnarySemantic context clusters
RulesServiceListRulesUnaryDerived business rules, with policies
RulesServiceAnalyzeCodeUnaryRules from the latest snapshot or from source code
RulesServiceCheckCodeUnaryModel review of a code snippet
RulesServiceUpdateRulePolicyUnarySet a rule’s enforcement policy

AnalysisService

Full name semantics.v1.AnalysisService.

These RPCs compute on the values in the request. They read no data source. Some errors are returned without a specific gRPC code, and clients see UNKNOWN for those.

AnalyzeTimeSeries

rpc AnalyzeTimeSeries(AnalyzeTimeSeriesRequest) returns (AnalyzeTimeSeriesResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: None. Too little data is reported in the response.

Runs an exploratory time-series analysis over data. The server chooses a Prophet decomposition or an ARIMA model by backtest, applies an ADF stationarity test (differencing a non-stationary series before modelling), and forecasts forecast_horizon steps. If no model fits, it falls back to linear regression and says so in recommended_model and anomalies. With 5 or fewer points, the response has only recommended_model: "Insufficient Data (Need > 5 points)".

Request: AnalyzeTimeSeriesRequest

FieldTypeDescription
datarepeated doubleThe series, in time order. More than 5 points are needed.
forecast_horizonint32Steps to forecast. 0 or negative means 3.
frequencystringSeries frequency label. Not used by the server.
domainstringDomain label. Not used by the server.
telemetry_sourcestringSource label. Not used by the server.

Response: AnalyzeTimeSeriesResponse

FieldTypeDescription
forecastrepeated doubleForecast values for the next forecast_horizon steps.
anomaliesrepeated stringFindings and anomalies, as sentences.
stationarity_teststringADF result, for example ADF: stationary (stat=… < crit5=…), or ADF: inconclusive. Empty on the fallback.
recommended_modelstringThe chosen model, for example ARIMA(1,1,0) [backtest-selected], or Linear Regression (Fallback).

AnalyzeFeature

rpc AnalyzeFeature(AnalyzeFeatureRequest) returns (AnalyzeFeatureResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: None.

Computes the autocorrelation of target at lags 1 to 5 and reports each lag with |ACF| > 0.5 as significant, with a target_lag_<k> feature for it. Fewer than 10 points returns generated_features: ["Insufficient data"], and a constant series returns ["Constant target"].

Request: AnalyzeFeatureRequest

FieldTypeDescription
targetrepeated doubleThe target series. At least 10 points.
external_varsrepeated doubleNot used by the server.

Response: AnalyzeFeatureResponse

FieldTypeDescription
significant_lagsrepeated stringFor example Lag-2 (ACF: 0.63).
generated_featuresrepeated stringFeature names such as target_lag_2, or a sentence when there are none.

ClusterRefinement

rpc ClusterRefinement(ClusterRefinementRequest) returns (ClusterRefinementResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: Returned without a specific code (clients see UNKNOWN) when vectors is empty, no vector has any dimensions, or clustering fails.

Clusters vectors with HDBSCAN (minimum cluster size 3, Euclidean distance), choosing parameters by silhouette. When the deployment has a re-ranking model, the clusters are refined with it, using BM25 scores of items against data_metadata (or telemetry_source) when items lines up with vectors. The dimension is taken from the first non-empty vector. Vectors of any other dimension are labelled noise (-1).

Request: ClusterRefinementRequest

FieldTypeDescription
itemsrepeated stringText items, one per vector. Used for BM25 scoring when the counts match.
granularitystringPARAGRAPH or COLUMN. Not used by the server.
vectorsrepeated EmbeddingRequired. The vectors to cluster.
domainstringContext for re-ranking.
access_levelstringContext for re-ranking.
telemetry_sourcestringContext for re-ranking, and the BM25 query when data_metadata is empty.
data_metadatastringContext for re-ranking, and the BM25 query.
business_unitstringNot used by the server.

Response: ClusterRefinementResponse

FieldTypeDescription
clustersrepeated int32A cluster label per input vector, in input order. -1 is noise.
noiserepeated int32Indices of the vectors labelled noise.
health_scoredoubleCluster quality: the silhouette score, or the re-ranker’s cluster health when refinement ran.

AnalyzeCausal

rpc AnalyzeCausal(AnalyzeCausalRequest) returns (AnalyzeCausalResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: INVALID_ARGUMENT if an edge is refused: an endpoint missing from nodes, or an edge that would create a cycle. An intervention failure is returned without a specific code.

Builds the graph exactly as you state it and sets intervention_node to intervention_value (the do-operator). The change propagates along edges by multiplying by each effect_size. With no edges, nothing propagates and the effect is 0. That means “no structure was given”, not “no effect was measured”. For a graph built from the connected estate, use AnalyzeEstateCausal.

Request: AnalyzeCausalRequest

FieldTypeDescription
nodesmap<string, double>Node name to observed value.
intervention_nodestringThe node to set.
intervention_valuedoubleThe value to set it to.
target_nodestringThe node whose change to report.
edgesrepeated CausalEdgeThe graph’s edges. Both endpoints must be in nodes, and the graph must stay acyclic.

Response: AnalyzeCausalResponse

FieldTypeDescription
effectdoublePredicted change in target_node. 0 when the target is not reached or not named.
new_target_valuedoubleThe target’s value after the intervention.

InferBayesian

rpc InferBayesian(InferBayesianRequest) returns (InferBayesianResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: FAILED_PRECONDITION on every call in the current release. No Bayesian network is defined on the instance, and the request cannot carry one.

Request: InferBayesianRequest

FieldTypeDescription
evidencemap<string, string>Variable to observed state.
target_nodestringThe variable whose posterior to return.

Response: InferBayesianResponse

FieldTypeDescription
probabilitiesmap<string, double>State to posterior probability. Not returned in the current release.

AnalyzeDescriptiveStats

rpc AnalyzeDescriptiveStats(AnalyzeDescriptiveStatsRequest) returns (AnalyzeDescriptiveStatsResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: None. Empty data returns an empty response, with every field 0.

Request: AnalyzeDescriptiveStatsRequest

FieldTypeDescription
datarepeated doubleThe values.

Response: AnalyzeDescriptiveStatsResponse

FieldTypeDescription
meandoubleMean.
mediandoubleMedian.
variancedoubleVariance.
std_devdoubleStandard deviation.
skewnessdoubleSkewness.
kurtosisdoubleKurtosis.

ClassifyESGRelevance

rpc ClassifyESGRelevance(ClassifyESGRelevanceRequest) returns (ClassifyESGRelevanceResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: Returned without a specific code if classification fails.

Scores the texts together for ESG relevance with a keyword classifier. No model is involved. The texts are also passed to the deployment’s knowledge-ingestion pipeline when one is configured.

Request: ClassifyESGRelevanceRequest

FieldTypeDescription
textsrepeated stringThe texts to score, as one group.

Response: ClassifyESGRelevanceResponse

FieldTypeDescription
relevance_scoredoubleESG relevance of the group.

PostureService

Full name semantics.v1.PostureService.

Posture comes from a fetch. After a fetch, GetHealthScore serves that run’s snapshot. Without a snapshot, the posture agent runs on the model plane. For how a fetch is started, see Fetch & traces. Long posture runs are visible live through ActivityService.

GetHealthScore

rpc GetHealthScore(GetHealthScoreRequest) returns (GetHealthScoreResponse);
  • Kind: Unary. It can take minutes when no snapshot exists and the posture agent has to run.
  • Auth: Bearer session.
  • Errors: FAILED_PRECONDITION if the instance has no data sources. UNAVAILABLE if the posture analysis cannot run. The server reports these rather than returning a grade it did not compute.

Returns the latest fetch’s posture snapshot, or runs the posture agent when there is none. Before it is returned, readiness figures are normalised, edges are cleaned, each assessment is assigned a domain, and each semantic context is grounded in the tenant’s knowledge corpus where one exists. graph_nodes and graph_edges are empty on this RPC.

Request: GetHealthScoreRequest

No fields.

Response: GetHealthScoreResponse

Also returned by BuildDomainGraph.

FieldTypeDescription
domainsmap<string, DomainHealth>Health per business domain.
assessmentsrepeated DataMaturityAssessmentData-maturity findings.
sopsrepeated OptimizationSOPRecommended measures.
contextsrepeated SemanticContextItemSemantic context clusters.
graph_nodesrepeated KnowledgeGraphNodeThe estate graph’s nodes. Set only by BuildDomainGraph with include_connected_sources.
graph_edgesrepeated KnowledgeGraphEdgeThe estate graph’s edges. Each edge’s evidence is in relation.

BuildDomainGraph

rpc BuildDomainGraph(BuildDomainGraphRequest) returns (GetHealthScoreResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: FAILED_PRECONDITION when include_connected_sources is false (there are no instance data files to map), when no data sources are configured, or when the server has no metadata store. INTERNAL if the configured connections cannot be listed.

With include_connected_sources: true, the server asks every configured connection for its catalogue (bounded at 30 seconds per source, concurrently), profiles columns, samples values except where excluded, and groups the discovered datasets into domains. A connection that refused, has no connector, or holds nothing still appears as a source node with its reason.

Sampled values are used only to infer structure. A sampled value never reaches the graph, a log line, an error, a lineage record or a model prompt: the graph carries counts and shapes, never a cell.

Request: BuildDomainGraphRequest

FieldTypeDescription
include_connected_sourcesboolDeprecated. Ask the connected sources. The cockpit’s estate map now uses the platform’s shared estate service. This field is still served, and without it the RPC refuses.
metadata_only_connection_idsrepeated stringConnections to read as catalogue only, with no rows sampled. Sampling is on by default for every other connection.

Response

GetHealthScoreResponse with graph_nodes and graph_edges set.

AnalyzeEstateCausal

rpc AnalyzeEstateCausal(AnalyzeEstateCausalRequest) returns (AnalyzeEstateCausalResponse);
  • Kind: Unary. It builds the estate graph first, so it has the same cost as BuildDomainGraph.
  • Auth: Bearer session.
  • Errors: The same preconditions as BuildDomainGraph. INVALID_ARGUMENT if the coefficients cannot be wired, for example because an effect_size is not finite.

Runs a do-intervention over estate causal nodes: columns of connected datasets that came back with a measured value. The structure comes from the coefficients you assert. The estate proposes candidate pairs but never supplies a coefficient. Without at least one admitted edge, the RPC refuses (answered: false) rather than returning an effect of 0. Read answered first, and show basis_statement beside any number.

Request: AnalyzeEstateCausalRequest

FieldTypeDescription
metadata_only_connection_idsrepeated stringAs in BuildDomainGraphRequest. An excluded connection contributes no causal node.
intervention_nodestringEstate causal node to set: <qualified dataset>.<column>.
intervention_valuedoubleValue to set it to.
target_nodestringEstate causal node whose change to report.
coefficientsrepeated EstateCausalCoefficientYour structural coefficients. At least one must be admitted.

Response: AnalyzeEstateCausalResponse

FieldTypeDescription
answeredboolfalse when nothing was propagated. Read this first.
refusalstringWhy it declined, in full. effect and new_target_value are 0 and meaningless then.
effectdoublePredicted change in the target.
new_target_valuedoubleTarget value after the intervention.
weakest_basisstringThe weakest basis among the edges used: OPERATOR_ASSERTED or DECLARED_KEY_REPURPOSED.
basis_statementstringWhat that basis means. Show it verbatim beside the number.
edgesrepeated stringEvery edge that entered the graph, basis first.
candidate_pairsrepeated stringEvery pair the estate proposed, priced or not.
node_refusalsrepeated stringColumns that were not made nodes, with reasons. Structure only, no figures.
edge_refusalsrepeated stringCoefficients that were not admitted, with reasons.
nodes_addedint32Causal nodes built.
columns_refusedint32Columns refused a node. Read nodes_added against it.

ListIncidents

rpc ListIncidents(ListIncidentsRequest) returns (ListIncidentsResponse);
  • Kind: Unary. It runs the posture agent.
  • Auth: Bearer session.
  • Errors: None. If the posture analysis cannot run, the list is empty. An empty list therefore does not mean “no incidents”.

Returns the posture agent’s data-maturity assessments. Entries that repeat the agent template’s example are dropped. domain is not set on this RPC.

Request: ListIncidentsRequest

No fields.

Response: ListIncidentsResponse

FieldTypeDescription
assessmentsrepeated DataMaturityAssessmentThe assessments.

GetContext

rpc GetContext(GetContextRequest) returns (GetContextResponse);
  • Kind: Unary. It runs the posture agent.
  • Auth: Bearer session.
  • Errors: None. If the posture analysis cannot run, it returns context_json: "{}" and no items.

Request: GetContextRequest

FieldTypeDescription
agent_typestringNot used by the server.

Response: GetContextResponse

FieldTypeDescription
context_jsonstringThe semantic contexts as JSON.
itemsrepeated SemanticContextItemThe same contexts, typed.

RulesService

Full name semantics.v1.RulesService.

A rule has two halves with different authors. Fields such as name, logic_plain_english, proposed_code and reconciliation_status are findings of the reconciliation agent, and nothing on this API can edit them. policy is the operator’s decision about the rule. It is written through UpdateRulePolicy and survives the next fetch.

ListRules

rpc ListRules(ListRulesRequest) returns (ListRulesResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: Returned without a specific code if the rules agent cannot run (for example, no model plane).

Derives rules from the latest fetch session’s analysis, using a cached result when one exists, then merges in each rule’s stored policy. With no fetch session yet, it returns an empty list.

Request: ListRulesRequest

FieldTypeDescription
domain_filterstringKeep only rules whose category equals this, case-insensitively. Empty returns all.

Response: ListRulesResponse

FieldTypeDescription
rulesrepeated RuleThe rules.

AnalyzeCode

rpc AnalyzeCode(AnalyzeCodeRequest) returns (AnalyzeCodeResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: FAILED_PRECONDITION when no rules snapshot exists and source_code is empty. Model, template and parse failures are returned without a specific code.

If a fetch has written a rules snapshot, returns those rules and ignores the request. Otherwise the reconciliation agent derives rules from source_code.

Request: AnalyzeCodeRequest

FieldTypeDescription
source_pathstringNot used by the server.
source_codestringCode to derive rules from, used only when no snapshot exists.

Response: AnalyzeCodeResponse

FieldTypeDescription
found_rulesrepeated RuleThe rules.

CheckCode

rpc CheckCode(CheckCodeRequest) returns (CheckCodeResponse);
  • Kind: Unary.
  • Auth: Bearer session.
  • Errors: PERMISSION_DENIED if the snippet trips the rules agent’s guardrail.

Asks the model plane to review the snippet. valid reports whether the model answered, not whether the code is valid. Read report.

Request: CheckCodeRequest

FieldTypeDescription
source_codestringThe code.
languagestringIts language.

Response: CheckCodeResponse

FieldTypeDescription
validbooltrue when the model answered. Not a verdict on the code.
issuesrepeated stringAlways empty.
reportstringThe model’s review, or the error when the call failed.

UpdateRulePolicy

rpc UpdateRulePolicy(UpdateRulePolicyRequest) returns (UpdateRulePolicyResponse);
  • Kind: Unary.
  • Auth: Bearer session. The author is the verified session subject.
  • Errors: INVALID_ARGUMENT if rule_id or policy is missing. UNAUTHENTICATED if the session has no subject. FAILED_PRECONDITION if no rules have been derived yet. NOT_FOUND if rule_id is not in the current rules. INTERNAL if the policy cannot be stored.

Stores the operator’s enforcement policy for an existing rule. It does not create rules. updated_by and updated_at_unix are set by the server.

Request: UpdateRulePolicyRequest

FieldTypeDescription
rule_idstringRequired. An existing rule’s id.
policyRulePolicyRequired. Author fields are ignored.

Response: UpdateRulePolicyResponse

FieldTypeDescription
policyRulePolicyThe stored policy, with the server-set author and time.

Messages

Embedding

FieldTypeDescription
vectorrepeated floatOne embedding vector.

CausalEdge

FieldTypeDescription
fromstringCause node.
tostringEffect node.
effect_sizedoubleStructural coefficient: a unit change in from moves to by this much. An edge at 0 is a declared non-relationship; a missing edge is an unknown one.

EstateCausalCoefficient

FieldTypeDescription
fromstringEstate causal node, <qualified dataset>.<column>, in the source’s own spelling. It must have a measured value.
tostringEstate causal node.
effect_sizedoubleYour assertion of the coefficient. Must be finite.

DomainHealth

FieldTypeDescription
statusstringStable, At Risk or Critical.
gradestringLetter grade, for example A, B or C.
quality_stability_pctdoubleQuality stability percentage.
risk_pii_pctdoublePII risk percentage.
lineage_pctdoubleLineage coverage percentage.
freshness_pctdoubleFreshness percentage.
policy_pctdoublePolicy coverage percentage.
cost_efficiency_pctdoubleCost efficiency percentage.
issuesstringIssues, as text.
uses_and_alignmentrepeated MaturityIndicatorMaturity indicators.
data_and_architecturerepeated MaturityIndicatorMaturity indicators.
analysis_and_predictiverepeated MaturityIndicatorMaturity indicators.
tools_and_automationrepeated MaturityIndicatorMaturity indicators.
skills_and_fluencyrepeated MaturityIndicatorMaturity indicators.
spatial_logisticsrepeated MaturityIndicatorMaturity indicators.
empty_triprepeated MaturityIndicatorAlways empty, on purpose. Nothing in the platform measures empty-trip running, so the server clears this field on every response. Display it as not measured.
shadow_search_ingestionrepeated MaturityIndicatorMaturity indicators.

MaturityIndicator

FieldTypeDescription
indicator_namestringIndicator name.
ratingint321 to 5.
metricstringThe metric.
descriptionstringDescription.

DataMaturityAssessment

FieldTypeDescription
incidentstringThe finding.
severitystringSeverity.
impactstringImpact.
root_causestringRoot cause.
blast_radiusstringBlast radius.
fixstringSuggested fix.
domainstringThe business domain it affects, matched against the fetch’s derived domains.

OptimizationSOP

FieldTypeDescription
typestringMeasure type.
titlestringTitle.
actionstringThe action.
reason_impactstringWhy, and the expected impact.
button_labelstringSuggested action label.
provenanceMeasureProvenanceWhere the wording came from. Only MEASURE_PROVENANCE_MODEL_GENERATED may be labelled AI-generated.

SemanticContextItem

FieldTypeDescription
cluster_namestringContext cluster name.
attributesstringAttributes.
relationshipsstringRelationships.
database_objectsrepeated stringDatabase objects in the cluster.
relevant_documentsrepeated stringRelevant documents.
quality_pillarsrepeated DataQualityPillarData-quality checks.
risk_checksrepeated RiskComplianceCheckRisk and compliance checks.

DataQualityPillar

FieldTypeDescription
namestringPillar name.
statusstringPass, Warning or Fail.
descriptionstringDescription.

RiskComplianceCheck

FieldTypeDescription
check_namestringCheck name.
statusstringPass, Warning or Fail.
detailsstringDetails.

KnowledgeGraphNode

FieldTypeDescription
idstringNode id.
labelstringDisplay label.
propertiesmap<string, string>Node properties.
domainstringBusiness domain.
access_levelstringAccess level.
telemetry_sourcestringTelemetry source.
data_metadatastringMetadata.
business_unitstringBusiness unit.

KnowledgeGraphEdge

FieldTypeDescription
sourcestringSource node id.
targetstringTarget node id.
relationstringThe edge’s evidence, as KIND or KIND: detail. DECLARED_FOREIGN_KEY is the source’s own constraint. INFERRED_* kinds are FACE’s measurements. GUESSED_* kinds are guesses and say so. Display the three differently.

Rule

FieldTypeDescription
idstringRule id.
namestringRule name.
logic_plain_englishstringThe rule in plain English.
source_documentstringDocument the rule was found in.
categorystringFor example Logistics or Finance.
severitystringCritical, High, Medium or Low.
maturitystringHigh, Medium or Low.
inferred_objectivestringThe rule’s inferred objective.
related_documentsrepeated stringRelated documents.
proposed_codestringProposed implementation.
rule_typestringRule type.
reconciliation_statusstringCode-versus-policy verdict: Aligned, Drift, Shadow or Missing. Empty means nobody has judged it, which is not Aligned.
implementation_filestringWhere the rule is implemented in code.
policy_documentstringThe governing policy document the agent grounded the rule in.
reconciliation_confidenceoptional doubleUnset on every response. Nothing measures a confidence for the verdict. Read reconciliation_status, and display an absent value as “not measured”.
policyRulePolicyThe operator’s enforcement policy.

RulePolicy

FieldTypeDescription
enforcement_actionEnforcementActionWhat happens on a breach.
tolerancestringTolerance in the rule’s own units, as typed.
policy_referencestringThe clause the operator cites, for example ISO-42001 §9.4.
updated_bystringServer-set. The verified subject that last wrote it.
updated_at_unixint64Server-set. 0 means never written.
rationalestringFree-text justification.

Enums

EnforcementAction

ValueMeaning
ENFORCEMENT_ACTION_UNSPECIFIEDNot set.
ENFORCEMENT_ACTION_AUDIT_ONLYObserve and record. Nothing is blocked.
ENFORCEMENT_ACTION_REVIEW_REQUIREDFlag the breach for a human before the action proceeds.
ENFORCEMENT_ACTION_BLOCKRefuse the action outright.

MeasureProvenance

ValueMeaning
MEASURE_PROVENANCE_UNSPECIFIEDWritten before this field existed. Says nothing.
MEASURE_PROVENANCE_MEASUREDRead verbatim from a source the fetch pulled.
MEASURE_PROVENANCE_DERIVEDComputed deterministically from measured data.
MEASURE_PROVENANCE_MODEL_GENERATEDWritten by a model.