Metadata-Version: 2.4
Name: reasoning_layer_python_sdk
Version: 1.6.0
Summary: A simple SDK package built in python for the Reasoning Layer tool by Kortexya
Author: David Loiret, Anexoms
Author-email: David Loiret <contact@kortexya.com>, Anexoms <maxence.pierre@epitech.eu>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: pydantic>=2.0
Requires-Dist: typing-extensions>=4.0
Requires-Dist: urllib3>=2.0
Requires-Dist: python-dateutil>=2.8
Requires-Python: >=3.10
Project-URL: Homepage, https://gitlab.com/kortexya/reasoninglayer-python-sdk
Project-URL: Issues, https://gitlab.com/kortexya/reasoninglayer-python-sdk/-/boards
Description-Content-Type: text/markdown

# Reasoning Layer Python SDK

A developer-friendly Python SDK for the Reasoning Layer API.
Wraps the OpenAPI-generated client with ergonomic resource clients, auto-coercion,
and builder utilities for complex types.

## Features

- **Domain-based resource clients** — `client.terms`, `client.sorts`, `client.inference`, `client.query`, `client.constraints`, `client.cognitive`
- **Auto-coercion** — pass plain Python primitives (`str`, `int`, `float`, `bool`, `UUID`) where the API expects `ValueDto` or `TermInputDto`
- **`Value` builders** — construct typed `ValueDto` instances ergonomically via `Value.string(...)`, `Value.integer(...)`, etc.
- **`TermInput` builders** — reference existing terms or create inline terms with `TermInput.reference(...)`, `TermInput.inline(...)`
- **Power-user escape hatch** — every method accepts a pre-built `request=...` object for full control

## Installation

```bash
pip install -e .
```

## Quick start

```python
from uuid import uuid4
from reasoning_layer_python_sdk import ReasoningLayerClient, ClientConfig, Value

config = ClientConfig(
    base_url="https://platform.ovh.reasoninglayer.ai",   # API base URL
    tenant_id="your-tenant-id",        # X-Tenant-Id header
    api_key="Bearer your-token",        # Authorization header
    user_id="optional-user-id",         # X-User-Id header
    namespace_id="optional-namespace",  # X-Namespace-Id header
    timeout_ms=30000,
    max_retries=3,
)

client = ReasoningLayerClient(config)

# Create a sort
sort = client.sorts.create(name="Person")

# Create a term with auto-coerced primitive features
person = client.terms.create(
    sort_id=sort.id,
    owner_id=uuid4(),
    features={"name": "Alice", "age": 30, "active": True},
)

# Or use Value builders for explicit typing
from reasoning_layer_python_sdk import Value
person = client.terms.create(
    sort_id=sort.id,
    owner_id=uuid4(),
    features={"name": Value.string("Alice"), "age": Value.integer(30)},
)
```

## Resource clients

### Terms (`client.terms`)

```python
# Create with auto-coerced features
term = client.terms.create(sort_id=sort_id, owner_id=tenant_id, features={"name": "Alice"})

# Get, update, delete
client.terms.get(term_id)
client.terms.update(term_id, features={"name": "Bob"})
client.terms.delete(term_id)

# Bulk operations
client.terms.bulk_create(terms=[...])
client.terms.clear()
```

### Sorts (`client.sorts`)

```python
sort = client.sorts.create(name="Person", parent_id=parent_id)
client.sorts.get(sort_id)
client.sorts.list()
client.sorts.delete(sort_id)

# Similarity
client.sorts.similarity.set(sort_a, sort_b, degree=0.9)
client.sorts.similarity.get(sort_a, sort_b)
client.sorts.similarity.learn(sort_a, sort_b, training_data=[...])

# Lattice operations
client.sorts.lattice.compute_glb([sort_a, sort_b])
client.sorts.lattice.compute_lub([sort_a, sort_b])
client.sorts.lattice.is_subtype(sub, sup)
```

### Inference (`client.inference`)

```python
# Add facts with auto-coercion
client.inference.add_fact(term_id)
client.inference.add_fact({"sort_id": sort_id, "features": {"name": "Alice"}})

# Chaining
client.inference.backward_chain(goal=goal_id)
client.inference.forward_chain(initial_facts=[fact_id1, fact_id2])
client.inference.fuzzy_prove(goal=goal_id, threshold=0.8)

# Goals
client.inference.create_goal(clause={"head": {...}, "body": [...]})
client.inference.get_goal(goal_id)
client.inference.delete_goal(goal_id)
```

### Query (`client.query`)

```python
# Find terms by sort
client.query.find_by_sort(sort_id=sort_id)

# Unification with auto-coerced dict patterns
client.query.find_unifiable(pattern={"sort_id": sort_id, "features": {"name": "Alice"}})

# Natural language query
client.query.nl_query(query="find all people", tenant_id=tenant_id)

# TRIZ inventive problem solving
client.query.triz_invent(
    tenant_id=tenant_id,
    improving_parameter="speed",
    worsening_parameter="cost",
)
```

### Constraints (`client.constraints`)

```python
# Incremental solving (session-based)
session = client.constraints.create_session(name="demo")
client.constraints.add_constraints(session.id, constraints=[{"type": "Plus", "left": "x", "right": 1}])
client.constraints.bind_variables(session.id, bindings={"x": 5})

# One-shot solve
client.constraints.solve(constraints=[...], initial_bindings={"x": 1})
```

### Cognitive (`client.cognitive`)

```python
# Agent lifecycle
agent = client.cognitive.create_agent(name="Alpha", tenant_id=tenant_id)
client.cognitive.get_agent(agent.id)
client.cognitive.run_cycle(agent_id=agent.id)
client.cognitive.run_integrated_cycle(agent_id=agent.id)

# Beliefs, goals, rules
client.cognitive.add_belief(agent_id=agent.id, belief={...})
client.cognitive.add_goal(agent_id=agent.id, goal={...})
client.cognitive.add_rule(agent_id=agent.id, head={...})

# Sub-clients
client.cognitive.memory.record_episode(agent_id=agent.id, ...)
client.cognitive.htn.decompose_goal(agent_id=agent.id, goal_id=goal_id)
client.cognitive.messaging.send(from_agent=..., to_agent=..., content={...})
client.cognitive.plans.store(agent_id=agent.id, plan={...})
```

## Builders

### `Value` — construct `ValueDto` instances

```python
from reasoning_layer_python_sdk import Value

Value.string("hello")
Value.integer(42)
Value.real(3.14)
Value.boolean(True)
Value.reference(term_id)
Value.uninstantiated()
Value.list_of(Value.string("a"), Value.string("b"))
Value.fuzzy_scalar(value=0.8, membership=1.0)
```

### `TermInput` — construct `TermInputDto` instances

```python
from reasoning_layer_python_sdk import TermInput

TermInput.reference(term_id)
TermInput.inline(sort_id=sort_id, features={"name": "Alice"})
TermInput.by_name(name="Person", features={"name": "Alice"})
```

## Configuration

```python
from reasoning_layer_python_sdk import ClientConfig

config = ClientConfig(
    base_url="http://localhost:8083",   # API base URL
    tenant_id="your-tenant-id",        # X-Tenant-Id header
    api_key="Bearer your-token",        # Authorization header
    user_id="optional-user-id",         # X-User-Id header
    namespace_id="optional-namespace",  # X-Namespace-Id header
    timeout_ms=30000,
    max_retries=3,
)
```

If `api_key` is omitted, the client falls back to the `API_KEY` environment variable.

## Error handling

All SDK errors inherit from `ReasoningLayerError`.

```python
from reasoning_layer_python_sdk.errors import ReasoningLayerError

try:
    client.terms.get(nonexistent_id)
except ReasoningLayerError as e:
    print(e.status_code, e.message)
```

## Running tests

```bash
pytest
```

## Project structure

```
src/reasoning_layer_python_sdk/
├── __init__.py          # Exports ReasoningLayerClient, ClientConfig, Value, TermInput
├── client.py            # Top-level ReasoningLayerClient
├── config.py            # ClientConfig dataclass
├── errors.py            # Custom exceptions
├── builders/            # Value and TermInput factories
│   └── __init__.py
└── resources/           # Ergonomic resource clients
    ├── cognitive.py
    ├── constraints.py
    ├── inference.py
    ├── query.py
    ├── sort.py
    └── terms.py
```

## Contributing

Contributions are welcome. Please open an issue or submit a PR.
