semantic-log-generator 1.0.5

Production-ready semantic RDF logging toolkit for SEGB-enabled robots

semantic_log_generator

Python package to build SEGB-compatible RDF logs and publish them to the centralized backend.

Compatibility

• Python: 3.10, 3.11, 3.12
• License: Apache-2.0
• Versioning: Semantic Versioning (see CHANGELOG.md)

What It Does

• Maps robot runtime facts to RDF triples
• Uses SEGB + PROV + ORO + ONYX + MLS + SOSA vocabularies
• Supports shared-event/shared-context linking across robots
• Publishes TTL payloads to backend /ttl
• Emits schema:provider links as resources (URI or materialized schema:Organization), not literals

What It Does Not Do

• Sensor acquisition
• ROS transport/orchestration
• Robot decision making
• KG reasoning

Install

From PyPI (when available)

python -m pip install semantic-log-generator

From TestPyPI (current published channel)

python -m pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  "semantic-log-generator>=1.0.5,<2.0.0"

From GitHub subdirectory

python -m pip install "git+https://github.com/gsi-upm/segb.git@<tag_or_commit>#subdirectory=packages/semantic_log_generator"

Quick Example

from datetime import datetime, timezone

from semantic_log_generator import ActivityKind, SemanticSEGBLogger

robot_id = "r1"
# base_namespace is generated by your application/deployment config.
# End users do not need to manipulate RDF/Turtle details.
base_namespace = f"https://example.org/segb/robots/{robot_id}/"

logger = SemanticSEGBLogger(
    base_namespace=base_namespace,
    robot_id=robot_id,
)

logger.log_activity(
    activity_id="listen_1",
    activity_kind=ActivityKind.LISTENING,
    started_at=datetime.now(timezone.utc),
)

ttl = logger.serialize(format="turtle")

Main APIs

• SemanticSEGBLogger
• SEGBPublisher
• HTTPSharedContextResolver
• ActivityKind, RobotStateSnapshot, EmotionScore, ModelUsage

Shared Context (Cross-Robot)

SemanticSEGBLogger does not auto-read environment variables and does not call POST /shared-context/resolve unless you pass a resolver explicitly.

To enable backend shared-context resolution, create a resolver and inject it:

from semantic_log_generator import SemanticSEGBLogger, build_http_shared_context_resolver_from_env

robot_id = "r1"
base_namespace = f"https://example.org/segb/robots/{robot_id}/"
resolver = build_http_shared_context_resolver_from_env()
logger = SemanticSEGBLogger(
    base_namespace=base_namespace,
    robot_id=robot_id,
    shared_event_resolver=resolver,
)

Environment variables for build_http_shared_context_resolver_from_env():

• General SEGB API configuration (recommended):
  • SEGB_API_URL
  • SEGB_API_TOKEN (only when backend auth is enabled)
• Optional:
  • SEGB_SHARED_CONTEXT_TIMEOUT_SECONDS (must be > 0, default 5.0)
  • SEGB_SHARED_CONTEXT_VERIFY_TLS (true/false, default true)
  • SEGB_SHARED_CONTEXT_RAISE_ON_ERROR (true/false, default false)

Shared Event RDF Shape

• Shared events are serialized as schema:Event and prov:Entity.
• event_kind and modality are still used for resolver/fingerprint logic, but are not emitted as schema:eventType/schema:measurementTechnique.
• When modality is provided, the logger emits a sosa:Observation linked to the shared event with:
  • sosa:hasFeatureOfInterest (the shared event)
  • sosa:usedProcedure (procedure resource labelled with modality, e.g. speech)
  • sosa:resultTime
  • sosa:hasSimpleResult (when text is available)
• Observation-to-shared-event confidence is emitted as schema:additionalProperty (schema:PropertyValue with schema:propertyID="shared_event_confidence").

Robot State RDF Shape

• Robot state snapshots are emitted as entities with schema:PropertyValue nodes.
• State properties are linked with schema:additionalProperty.
• State location is linked with prov:atLocation.

Related Docs

• Installation guide: docs/package/installation.md
• Usage guide: docs/package/usage.md
• Internal TTL generation: docs/internals/ttl-generation.md

Tests

Package-specific tests are in packages/semantic_log_generator/tests/unit.

PYTHONPATH=packages/semantic_log_generator/src:apps/backend/src ./.venv/bin/python -m unittest discover -s packages/semantic_log_generator/tests/unit -p 'test_*.py'