abstractsemantics 0.0.1__tar.gz

abstractsemantics-0.0.1/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: abstractsemantics
+Version: 0.0.1
+Summary: Semantics registry (predicates/types) for AbstractFramework.
+Author: Laurent-Philippe Albou
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# AbstractSemantics
+
+Central, editable semantics registry for AbstractFramework.
+
+This package intentionally contains **definitions**, not storage:
+- prefix mappings (CURIE namespaces)
+- predicate allowlists (and optional inverses/constraints)
+- entity-type allowlists (optional in v0)
+
+It is designed to be consumed by:
+- AbstractRuntime (validation at ingestion boundary)
+- AbstractFlow (UI dropdowns + authoring support)
+- AbstractMemory (storage/query on top of validated semantics)
+

abstractsemantics-0.0.1/README.md

@@ -0,0 +1,14 @@
+# AbstractSemantics
+
+Central, editable semantics registry for AbstractFramework.
+
+This package intentionally contains **definitions**, not storage:
+- prefix mappings (CURIE namespaces)
+- predicate allowlists (and optional inverses/constraints)
+- entity-type allowlists (optional in v0)
+
+It is designed to be consumed by:
+- AbstractRuntime (validation at ingestion boundary)
+- AbstractFlow (UI dropdowns + authoring support)
+- AbstractMemory (storage/query on top of validated semantics)
+

abstractsemantics-0.0.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "abstractsemantics"
+version = "0.0.1"
+description = "Semantics registry (predicates/types) for AbstractFramework."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Laurent-Philippe Albou" }]
+dependencies = [
+  "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["abstractsemantics*"]
+exclude = ["tests*"]
+
+[tool.setuptools.package-data]
+abstractsemantics = ["*.yaml", "*.yml"]

abstractsemantics-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

abstractsemantics-0.0.1/src/abstractsemantics/__init__.py

@@ -0,0 +1,19 @@
+from .registry import (
+    SemanticsRegistry,
+    load_semantics_registry,
+    resolve_semantics_registry_path,
+)
+from .schema import (
+    KG_ASSERTION_SCHEMA_REF_V0,
+    build_kg_assertion_schema_v0,
+    resolve_schema_ref,
+)
+
+__all__ = [
+    "SemanticsRegistry",
+    "load_semantics_registry",
+    "resolve_semantics_registry_path",
+    "KG_ASSERTION_SCHEMA_REF_V0",
+    "build_kg_assertion_schema_v0",
+    "resolve_schema_ref",
+]

abstractsemantics-0.0.1/src/abstractsemantics/registry.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+import yaml
+
+
+@dataclass(frozen=True)
+class PredicateDef:
+    id: str
+    label: Optional[str] = None
+    inverse: Optional[str] = None
+    description: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class EntityTypeDef:
+    id: str
+    label: Optional[str] = None
+    parent: Optional[str] = None
+    description: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class SemanticsRegistry:
+    version: int
+    prefixes: Dict[str, str]
+    predicates: List[PredicateDef]
+    entity_types: List[EntityTypeDef]
+
+    def predicate_ids(self) -> set[str]:
+        return {p.id for p in self.predicates if isinstance(p.id, str) and p.id.strip()}
+
+    def entity_type_ids(self) -> set[str]:
+        return {t.id for t in self.entity_types if isinstance(t.id, str) and t.id.strip()}
+
+
+def resolve_semantics_registry_path() -> Path:
+    """Resolve the registry YAML path.
+
+    Env override:
+    - ABSTRACTSEMANTICS_REGISTRY_PATH
+    """
+    raw = os.getenv("ABSTRACTSEMANTICS_REGISTRY_PATH")
+    if isinstance(raw, str) and raw.strip():
+        p = Path(raw).expanduser().resolve()
+        if not p.exists():
+            raise FileNotFoundError(f"ABSTRACTSEMANTICS_REGISTRY_PATH does not exist: {p}")
+        return p
+    return Path(__file__).with_name("semantics.yaml")
+
+
+def _as_list(value: Any) -> list:
+    return list(value) if isinstance(value, list) else []
+
+
+def _load_yaml(path: Path) -> Dict[str, Any]:
+    raw = path.read_text(encoding="utf-8")
+    data = yaml.safe_load(raw)
+    return data if isinstance(data, dict) else {}
+
+
+def load_semantics_registry(path: Path | None = None) -> SemanticsRegistry:
+    p = path or resolve_semantics_registry_path()
+    data = _load_yaml(p)
+
+    version_raw = data.get("version", 0)
+    try:
+        version = int(version_raw)
+    except Exception:
+        version = 0
+
+    prefixes_raw = data.get("prefixes")
+    prefixes: Dict[str, str] = {}
+    if isinstance(prefixes_raw, dict):
+        for k, v in prefixes_raw.items():
+            if isinstance(k, str) and isinstance(v, str) and k.strip() and v.strip():
+                prefixes[k.strip()] = v.strip()
+
+    predicates: list[PredicateDef] = []
+    for item in _as_list(data.get("predicates")):
+        if not isinstance(item, dict):
+            continue
+        pid = item.get("id")
+        if not isinstance(pid, str) or not pid.strip():
+            continue
+        predicates.append(
+            PredicateDef(
+                id=pid.strip(),
+                label=item.get("label") if isinstance(item.get("label"), str) else None,
+                inverse=item.get("inverse") if isinstance(item.get("inverse"), str) else None,
+                description=item.get("description") if isinstance(item.get("description"), str) else None,
+            )
+        )
+
+    entity_types: list[EntityTypeDef] = []
+    for item in _as_list(data.get("entity_types")):
+        if not isinstance(item, dict):
+            continue
+        tid = item.get("id")
+        if not isinstance(tid, str) or not tid.strip():
+            continue
+        entity_types.append(
+            EntityTypeDef(
+                id=tid.strip(),
+                label=item.get("label") if isinstance(item.get("label"), str) else None,
+                parent=item.get("parent") if isinstance(item.get("parent"), str) else None,
+                description=item.get("description") if isinstance(item.get("description"), str) else None,
+            )
+        )
+
+    if not predicates:
+        raise ValueError(f"Semantics registry has no predicates: {p}")
+
+    return SemanticsRegistry(
+        version=version,
+        prefixes=prefixes,
+        predicates=predicates,
+        entity_types=entity_types,
+    )
+
+

abstractsemantics-0.0.1/src/abstractsemantics/schema.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence
+
+from .registry import SemanticsRegistry, load_semantics_registry
+
+# Stable reference strings for flow-authored schemas.
+#
+# Visual flows may reference these via a `json_schema` literal like:
+#   {"$ref": "abstractsemantics:kg_assertion_schema_v0"}
+# The runtime resolves them into a concrete JSON Schema dict at execution time.
+KG_ASSERTION_SCHEMA_REF_V0 = "abstractsemantics:kg_assertion_schema_v0"
+
+
+# Small, deterministic alias set for predicates that LLMs tend to emit by default.
+#
+# These are *not* part of the canonical semantics registry. Prefer keeping
+# structured-output enums canonical (so the model is forced to pick from the
+# agreed semantics). Alias handling belongs at the ingestion boundary.
+#
+# Keep this list intentionally small to protect model context + reduce confusion.
+KG_PREDICATE_ALIASES_V0: Sequence[str] = (
+    "schema:description",
+    "schema:creator",
+    "schema:hasParent",
+    "schema:hasMember",
+    "schema:recognizedAs",
+    "schema:hasMemorySource",
+    "schema:hasPart",
+    "schema:isPartOf",
+    "dcterms:has_part",
+    "dcterms:is_part_of",
+)
+
+
+def _dedup_preserve_order(values: Sequence[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for v in values:
+        if not isinstance(v, str):
+            continue
+        v2 = v.strip()
+        if not v2 or v2 in seen:
+            continue
+        seen.add(v2)
+        out.append(v2)
+    return out
+
+
+def build_kg_assertion_schema_v0(
+    registry: Optional[SemanticsRegistry] = None,
+    *,
+    include_predicate_aliases: bool = False,
+    max_assertions: int = 12,
+    min_assertions_when_nonempty: int = 3,
+    max_evidence_quote_len: int = 160,
+    max_original_context_len: int = 280,
+) -> Dict[str, Any]:
+    """Build the structured-output JSON Schema used by the KG extractor workflows.
+
+    This schema is deliberately small and meant to be stable:
+    - `predicate` is restricted to the semantics registry (+ optional aliases).
+    - `subject_type` / `object_type` are restricted to the registry entity types.
+    - Evidence fields are bounded (short verbatim snippets).
+    """
+    reg = registry or load_semantics_registry()
+
+    predicate_ids: List[str] = [p.id for p in reg.predicates if isinstance(p.id, str) and p.id.strip()]
+    if include_predicate_aliases:
+        predicate_ids = list(predicate_ids) + list(KG_PREDICATE_ALIASES_V0)
+    predicate_ids = _dedup_preserve_order(predicate_ids)
+
+    entity_type_ids: List[str] = [t.id for t in reg.entity_types if isinstance(t.id, str) and t.id.strip()]
+    entity_type_ids = _dedup_preserve_order(entity_type_ids)
+
+    if not predicate_ids:
+        raise ValueError("Semantics registry provided no predicate ids")
+    if not entity_type_ids:
+        raise ValueError("Semantics registry provided no entity type ids")
+
+    max_assertions2 = max(0, int(max_assertions))
+    min_nonempty2 = max(0, int(min_assertions_when_nonempty))
+    if max_assertions2 and min_nonempty2 and min_nonempty2 > max_assertions2:
+        min_nonempty2 = max_assertions2
+
+    assertions_schema: Dict[str, Any] = {
+        "type": "array",
+        "items": {
+            "type": "object",
+            "properties": {
+                "subject": {"type": "string"},
+                "predicate": {"type": "string", "enum": predicate_ids},
+                "object": {"type": "string"},
+                "confidence": {"type": ["number", "null"], "minimum": 0, "maximum": 1},
+                "valid_from": {"type": ["string", "null"]},
+                "valid_until": {"type": ["string", "null"]},
+                "provenance": {"type": ["object", "null"]},
+                "attributes": {
+                    "type": "object",
+                    "properties": {
+                        "subject_type": {"type": "string", "enum": entity_type_ids},
+                        "object_type": {"type": "string", "enum": entity_type_ids},
+                        "evidence_quote": {"type": "string", "maxLength": int(max_evidence_quote_len)},
+                        "original_context": {"type": "string", "maxLength": int(max_original_context_len)},
+                    },
+                    "required": ["evidence_quote"],
+                },
+            },
+            "required": ["subject", "predicate", "object", "attributes"],
+        },
+    }
+
+    if max_assertions2:
+        assertions_schema["maxItems"] = max_assertions2
+    if min_nonempty2:
+        # Either:
+        # - empty list (no facts), OR
+        # - at least N assertions (avoid low-signal singletons that “technically” validate).
+        assertions_schema["anyOf"] = [{"maxItems": 0}, {"minItems": min_nonempty2}]
+
+    return {
+        "type": "object",
+        "properties": {
+            "assertions": assertions_schema
+        },
+        "required": ["assertions"],
+    }
+
+
+def resolve_schema_ref(schema: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Resolve a schema reference dict to a concrete JSON Schema (if supported)."""
+    ref = schema.get("$ref")
+    if isinstance(ref, str) and ref.strip():
+        if ref.strip() == KG_ASSERTION_SCHEMA_REF_V0:
+            return build_kg_assertion_schema_v0()
+    return None

abstractsemantics-0.0.1/src/abstractsemantics/semantics.yaml

@@ -0,0 +1,164 @@
+version: 0
+
+prefixes:
+  dcterms: "http://purl.org/dc/terms/"
+  schema: "https://schema.org/"
+  skos: "http://www.w3.org/2004/02/skos/core#"
+  cito: "http://purl.org/spar/cito/"
+  rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+  ex: "http://example.org/"
+
+# v0 policy: predicate allowlist for ingestion validation + UI dropdowns.
+# Source: docs/guide/semantics/semantic-triple-prompt-v4-optimized.md (preferred predicates)
+predicates:
+  - id: "rdf:type"
+    label: "type"
+    description: "Class membership (entity -> class)."
+
+  # Structure
+  - id: "dcterms:hasPart"
+    label: "has part"
+    inverse: "dcterms:isPartOf"
+  - id: "dcterms:isPartOf"
+    label: "is part of"
+    inverse: "dcterms:hasPart"
+  - id: "schema:nextItem"
+    label: "next item"
+    inverse: "schema:previousItem"
+  - id: "schema:previousItem"
+    label: "previous item"
+    inverse: "schema:nextItem"
+
+  # Metadata
+  - id: "dcterms:identifier"
+    label: "identifier"
+  - id: "dcterms:title"
+    label: "title"
+  - id: "schema:name"
+    label: "name"
+    description: "Primary label for non-document entities (agents, events, places, etc.)."
+  - id: "dcterms:description"
+    label: "description"
+  - id: "dcterms:abstract"
+    label: "abstract"
+  - id: "dcterms:created"
+    label: "created"
+  - id: "dcterms:modified"
+    label: "modified"
+  - id: "dcterms:creator"
+    label: "creator"
+  - id: "dcterms:publisher"
+    label: "publisher"
+  - id: "dcterms:subject"
+    label: "subject"
+  - id: "schema:genre"
+    label: "genre"
+
+  # Context & anchors
+  - id: "schema:about"
+    label: "about"
+  - id: "schema:mentions"
+    label: "mentions"
+  - id: "schema:knowsAbout"
+    label: "knows about"
+    description: "An agent's knowledge/awareness about a topic or entity (stronger than incidental mentions)."
+  - id: "dcterms:references"
+    label: "references"
+  - id: "schema:sameAs"
+    label: "same as"
+  - id: "schema:location"
+    label: "location"
+  - id: "schema:temporalCoverage"
+    label: "temporal coverage"
+
+  # Action & participants
+  - id: "schema:participant"
+    label: "participant"
+  - id: "schema:organizer"
+    label: "organizer"
+  - id: "schema:result"
+    label: "result"
+  - id: "schema:instrument"
+    label: "instrument"
+  - id: "schema:startDate"
+    label: "start date"
+  - id: "schema:endDate"
+    label: "end date"
+
+  # Concepts
+  - id: "skos:definition"
+    label: "definition"
+  - id: "skos:prefLabel"
+    label: "preferred label"
+  - id: "skos:altLabel"
+    label: "alternative label"
+  - id: "skos:broader"
+    label: "broader"
+  - id: "skos:narrower"
+    label: "narrower"
+  - id: "skos:related"
+    label: "related"
+  - id: "skos:exactMatch"
+    label: "exact match"
+  - id: "skos:closeMatch"
+    label: "close match"
+
+  # Evidence
+  - id: "cito:supports"
+    label: "supports"
+  - id: "cito:disagreesWith"
+    label: "disagrees with"
+  - id: "cito:usesDataFrom"
+    label: "uses data from"
+    inverse: "cito:providesDataFor"
+  - id: "cito:providesDataFor"
+    label: "provides data for"
+    inverse: "cito:usesDataFrom"
+  - id: "cito:extends"
+    label: "extends"
+  - id: "cito:discusses"
+    label: "discusses"
+  - id: "cito:confirms"
+    label: "confirms"
+
+entity_types:
+  # Generic "real-world thing" catch-all (includes physical objects).
+  - id: "schema:Thing"
+    label: "Thing"
+
+  - id: "dcterms:Text"
+    label: "Text"
+  - id: "dcterms:Collection"
+    label: "Collection"
+  - id: "skos:Concept"
+    label: "Concept"
+  - id: "cito:Claim"
+    label: "Claim"
+  - id: "schema:Person"
+    label: "Person"
+  - id: "schema:Organization"
+    label: "Organization"
+  - id: "schema:ItemList"
+    label: "List"
+  - id: "schema:SoftwareApplication"
+    label: "Software Application"
+  - id: "schema:Event"
+    label: "Event"
+  - id: "schema:Place"
+    label: "Place"
+  - id: "schema:Country"
+    label: "Country"
+    parent: "schema:Place"
+  - id: "schema:Product"
+    label: "Product"
+    parent: "schema:Thing"
+  - id: "schema:Dataset"
+    label: "Dataset"
+  - id: "schema:ImageObject"
+    label: "Image"
+  - id: "schema:VideoObject"
+    label: "Video"
+  - id: "schema:Table"
+    label: "Table"
+  - id: "schema:SoftwareSourceCode"
+    label: "Code"

abstractsemantics-0.0.1/src/abstractsemantics.egg-info/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: abstractsemantics
+Version: 0.0.1
+Summary: Semantics registry (predicates/types) for AbstractFramework.
+Author: Laurent-Philippe Albou
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# AbstractSemantics
+
+Central, editable semantics registry for AbstractFramework.
+
+This package intentionally contains **definitions**, not storage:
+- prefix mappings (CURIE namespaces)
+- predicate allowlists (and optional inverses/constraints)
+- entity-type allowlists (optional in v0)
+
+It is designed to be consumed by:
+- AbstractRuntime (validation at ingestion boundary)
+- AbstractFlow (UI dropdowns + authoring support)
+- AbstractMemory (storage/query on top of validated semantics)
+

abstractsemantics-0.0.1/src/abstractsemantics.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/abstractsemantics/__init__.py
+src/abstractsemantics/registry.py
+src/abstractsemantics/schema.py
+src/abstractsemantics/semantics.yaml
+src/abstractsemantics.egg-info/PKG-INFO
+src/abstractsemantics.egg-info/SOURCES.txt
+src/abstractsemantics.egg-info/dependency_links.txt
+src/abstractsemantics.egg-info/requires.txt
+src/abstractsemantics.egg-info/top_level.txt
+tests/test_registry.py
+tests/test_schema.py

abstractsemantics-0.0.1/src/abstractsemantics.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

abstractsemantics-0.0.1/src/abstractsemantics.egg-info/requires.txt

@@ -0,0 +1,4 @@
+PyYAML>=6.0
+
+[dev]
+pytest>=7.0.0

abstractsemantics-0.0.1/src/abstractsemantics.egg-info/top_level.txt

@@ -0,0 +1 @@
+abstractsemantics

abstractsemantics-0.0.1/tests/test_registry.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from abstractsemantics import load_semantics_registry
+
+
+def test_load_semantics_registry_has_predicates():
+    reg = load_semantics_registry()
+    ids = reg.predicate_ids()
+    assert "rdf:type" in ids
+    assert "dcterms:isPartOf" in ids
+

abstractsemantics-0.0.1/tests/test_schema.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from abstractsemantics import (
+    KG_ASSERTION_SCHEMA_REF_V0,
+    build_kg_assertion_schema_v0,
+    load_semantics_registry,
+    resolve_schema_ref,
+)
+
+
+def test_build_kg_assertion_schema_v0_tracks_registry_predicates_and_types() -> None:
+    reg = load_semantics_registry()
+    schema = build_kg_assertion_schema_v0(registry=reg, include_predicate_aliases=True)
+
+    pred_enum = schema["properties"]["assertions"]["items"]["properties"]["predicate"]["enum"]
+    assert isinstance(pred_enum, list) and pred_enum
+    for pid in reg.predicate_ids():
+        assert pid in pred_enum
+
+    type_enum = schema["properties"]["assertions"]["items"]["properties"]["attributes"]["properties"]["subject_type"]["enum"]
+    assert isinstance(type_enum, list) and type_enum
+    for tid in reg.entity_type_ids():
+        assert tid in type_enum
+
+
+def test_build_kg_assertion_schema_v0_can_disable_aliases() -> None:
+    reg = load_semantics_registry()
+    schema = build_kg_assertion_schema_v0(registry=reg, include_predicate_aliases=False)
+    pred_enum = schema["properties"]["assertions"]["items"]["properties"]["predicate"]["enum"]
+    assert "schema:creator" not in pred_enum
+    assert "schema:description" not in pred_enum
+
+
+def test_resolve_schema_ref_returns_concrete_schema() -> None:
+    resolved = resolve_schema_ref({"$ref": KG_ASSERTION_SCHEMA_REF_V0})
+    assert isinstance(resolved, dict)
+    assert resolved.get("type") == "object"
+    assert "assertions" in resolved.get("properties", {})
+