Package ai.chatur.cortex.core.ingest

Class IngestService

java.lang.Object
ai.chatur.cortex.core.ingest.IngestService
public class IngestService extends Object
Validates incoming RDF assertions, and proposed edits to approved ones, and stages them on a new branch pending review.

Incoming assertions are linted against the ontology, validated against SHACL shapes together with the approved assertions, trimmed of triples already approved, and staged on a branch — a named graph within the assertions dataset. Every branch carries a provenance activity recording the ingestion, built by the ProvenanceRecorder. Reviewing, editing, and resolving a branch once it is staged are the jobs of core.branch's services, not this one.

revise(ai.chatur.cortex.ResourceEdit) stages the other kind of proposal: a change to statements that are already approved. It is the same pipeline and produces the same kind of branch, so the rule that nothing reaches the approved assertions without review holds for edits exactly as it does for new claims. The one structural difference is that an edit has to retract as well as assert, which the branch carries in its retraction graph.

  • Constructor Summary

    Constructors
    Constructor
    Description
    IngestService(org.apache.jena.query.Dataset assertions, LintService lintService, ProvenanceRecorder provenanceRecorder)
    Creates the service.

  • Method Summary

    Modifier and Type
    Method
    Description
    ai.chatur.cortex.IngestResult
    ingest(String ttl)
    Lints and validates the given assertions and stages them on a new branch.
    ai.chatur.cortex.IngestResult
    revise(ai.chatur.cortex.ResourceEdit edit)
    Stages a proposed edit to an already-approved resource on a new branch.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • IngestService

      public IngestService(org.apache.jena.query.Dataset assertions, LintService lintService, ProvenanceRecorder provenanceRecorder)
      Creates the service.
      Parameters:
      assertions - the dataset holding the approved assertions and the staged branches
      lintService - the lint check and SHACL validation incoming assertions must pass
      provenanceRecorder - builds the provenance activity recorded when a branch is staged

  • Method Details

    • ingest

      public ai.chatur.cortex.IngestResult ingest(String ttl)
      Lints and validates the given assertions and stages them on a new branch.

      Assertions that cannot be parsed, fail the lint check against the ontology, or do not conform to the shapes are not staged; the problem is reported in the result instead. The shapes are validated against the union of the approved assertions and the incoming ones, so incoming assertions may rely on already approved statements to conform.

      Incoming triples already present among the approved assertions are trimmed before staging, so a branch only ever carries novel statements. If every triple is already approved, nothing is staged and the result carries no branch. The staged branch also carries a provenance activity recording when the ingestion was staged.

      The SHACL validation, the novelty diff, and the staging write all happen inside one write transaction on the assertions dataset, so a concurrent approve landing between the validation and the write can no longer make either stale: TDB2 serializes writers, so this ingestion either sees the approval's result in full (and validates and diffs against it) or runs entirely before it. Parsing the incoming Turtle happens first, outside the transaction, since it depends on nothing from the dataset.

      Parameters:
      ttl - RDF assertions in Turtle syntax
      Returns:
      the outcome, carrying either the name of the created branch — null if every triple was already approved — or the errors

    • revise

      public ai.chatur.cortex.IngestResult revise(ai.chatur.cortex.ResourceEdit edit)
      Stages a proposed edit to an already-approved resource on a new branch.

      Changing the value of an approved statement is a retraction and an assertion, not just an assertion, so the branch this stages carries both: the novel statements in the branch graph and the statements to remove in its retraction graph. Neither takes effect until the branch is approved.

      The additions are linted against the ontology, and the SHACL shapes are validated against the assertions as they would be once the branch is approved — the approved statements minus the retractions, plus the additions. That is stricter than ingest(java.lang.String), which validates a union and so can only ever see constraints satisfied: a retraction can take away the statement that was satisfying a constraint, and validating the union would not notice.

      A rename is applied after the changes, since the changes address the resource by its current IRI. It rewrites every statement in which the IRI appears — as subject or as object — so no reference is left pointing at a resource that no longer exists.

      Additions already approved and retractions of statements that are not approved are dropped, as is any statement the same edit both retracts and asserts. If nothing remains, no branch is created and the result carries none, exactly as an ingest of entirely known statements does.

      Parameters:
      edit - the proposed edit
      Returns:
      the outcome, carrying either the name of the created branch — null if the edit would change nothing — or the lint or validation errors