Metadata-Version: 2.4
Name: semantic-log-generator
Version: 1.0.5
Summary: Production-ready semantic RDF logging toolkit for SEGB-enabled robots
Author-email: José Luis Benítez Santana <jose.benitez.upm@gmail.com>
Maintainer-email: José Luis Benítez Santana <jose.benitez.upm@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gsi-upm/semantic_ethical_glass_box
Project-URL: Repository, https://github.com/gsi-upm/semantic_ethical_glass_box
Project-URL: Documentation, https://semantic-ethical-black-box-segb.readthedocs.io/en/stable/
Project-URL: Issues, https://github.com/gsi-upm/semantic_ethical_glass_box/issues
Project-URL: Changelog, https://github.com/gsi-upm/semantic_ethical_glass_box/blob/main/packages/semantic_log_generator/CHANGELOG.md
Keywords: segb,semantic-logging,rdf,ros2,knowledge-graph,explainability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rdflib<8,>=7.1.3
Requires-Dist: requests<3,>=2.31.0
Provides-Extra: dev
Requires-Dist: ruff<0.12,>=0.11; extra == "dev"
Requires-Dist: mypy<2.0,>=1.15; extra == "dev"
Dynamic: license-file

# `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`](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)

```bash
python -m pip install semantic-log-generator
```

### From TestPyPI (current published channel)

```bash
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

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

## Quick Example

```python
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:

```python
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`](https://github.com/gsi-upm/semantic_ethical_glass_box/blob/main/docs/package/installation.md)
- Usage guide: [`docs/package/usage.md`](https://github.com/gsi-upm/semantic_ethical_glass_box/blob/main/docs/package/usage.md)
- Internal TTL generation: [`docs/internals/ttl-generation.md`](https://github.com/gsi-upm/semantic_ethical_glass_box/blob/main/docs/internals/ttl-generation.md)

## Tests

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

```bash
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'
```
