Skip to main content

Diff & Merge API

Compare and combine semantic state.

Semantic Diff​

POST /api/v1/diff

Request​

{
  "base_commit_hash": "sha256:abc...",
  "target_commit_hash": "sha256:xyz..."
}

Response​

{
  "facet_changes": [
    {
      "type": "added",
      "facet": "budget",
      "keywords": ["$1000", "cheap"]
    },
    {
      "type": "removed",
      "facet": "luxury",
      "keywords": ["5-star", "premium"]
    },
    {
      "type": "modified",
      "facet": "accommodation",
      "added_keywords": ["hostel"],
      "removed_keywords": ["hotel"]
    }
  ],
  "segment_changes": [
    {
      "type": "semantic_shift",
      "similarity": 0.45,
      "base_segment": "Stay at luxury hotels",
      "target_segment": "Book budget hostels"
    }
  ]
}

Three-Way Merge​

POST /api/v1/merge

Request​

{
  "base_commit_hash": "sha256:base...",
  "source_commit_hash": "sha256:feature...",
  "target_commit_hash": "sha256:main..."
}

Response​

{
  "auto_merged_facets": [
    {
      "facet": "transportation",
      "merged_keywords": ["train", "bus", "subway"]
    }
  ],
  "merge_conflicts": [
    {
      "facet": "accommodation",
      "conflict_type": "semantic_divergence",
      "source_keywords": ["hostel"],
      "target_keywords": ["hotel"],
      "similarity": 0.32
    }
  ]
}

Conflicts occur when similarity falls below 0.70 threshold.