reasoning_layer_python_sdk 1.0.0

A simple SDK package built in python for the Reasoning Layer tool by Kortexya

Reasoning Layer Python SDK

A developer-friendly Python SDK for the Reasoning Layer API (OSF Knowledge Base). 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

pip install -e .

Quick start

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

config = ClientConfig(
    base_url="http://localhost:8083",
    tenant_id="550e8400-e29b-41d4-a716-446655440000",
    api_key="Bearer your-token",
)

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)

# 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)

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)

# 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)

# 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)

# 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)

# 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

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

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

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.

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

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.