souslesens

Python client for the SousLesSensVocables API.

Installation

pip install souslesens

Quick start

from souslesens import SlsClient

client = SlsClient(token="xxx", base_url="http://localhost:3010")
client.health()
client.ask.knowledge_model_graph("ISO-14224-IOF")

API

Each method mirrors the API path it calls. The /api/v1/ask/... endpoints live under client.ask.

Adding a new endpoint

A route inside an existing group (for example the /api/v1/ask/... endpoints under client.ask):

1. Add a method to the group class in souslesens/client.py (e.g. Ask) that calls get_json(self._client.base_url, path, self._client.token, params=...).
2. Mirror it in souslesens/testing.py: override the method in the mock group class (e.g. MockAsk) to delegate to self._client._get("<method_name>"), and add the default response to MockSlsClient.DEFAULT_RESPONSES.
3. Add a test in tests/test_client.py asserting the URL and the params, then a row in the API table above.

A route in a new group (anything not under an existing one) needs a new group class, on the model of Ask:

1. In client.py, define the class (its __init__ stores the client, one method per route) and instantiate it in SlsClient.__init__, next to self.ask = Ask(self).
2. In testing.py, define a mock subclass overriding each method to delegate to self._client._get(...), add its default responses to DEFAULT_RESPONSES, and instantiate it in MockSlsClient.__init__.
3. Add the same test and API table row.

Run uv run pytest then uv run ruff check.

Health response

The health value is a mapping of probed services to booleans (virtuoso, elasticsearch, spacyserver by default). The keys depend on the server-side health_enabled_services config.

data = client.health()
if data["health"] == "error":
    # server could not probe itself — see HealthCheckError below
    ...
if not all(data["health"].values()):
    # at least one upstream service is down
    ...

Exceptions

• SlsClientError — base class for all client failures (network error, invalid JSON response).
• HealthCheckError(SlsClientError) — the server returned {"health": "error"} (it could not probe itself).

Testing

A drop-in mock replaces SlsClient without any network calls. Inject the health payload and inspect recorded calls:

from souslesens.testing import MockSlsClient

client = MockSlsClient(health={"health": {"virtuoso": True, "elasticsearch": False, "spacyserver": True}})
data = client.health()  # returns the injected payload
assert client.calls == ["health"]

Development

uv run pytest
uv run pytest --cov
uv run ruff check
uv build