Documentation

Learn the concepts and tools behind Pod-OS

Python SDK

The pod-os-py-client library is an asyncio client for registering as a Pod-OS Actor or talking to Actors over the AIP message protocol, including Evolutionary Neural Memory Intents.

Repository: github.com/PointOfData/pod-os-py-client

Requires Python 3.12+.

Install

pip install pod-os-py-client

# Optional faster event loop
pip install pod-os-py-client[uvloop]

Connect

Dial the gateway TCP endpoint and set gateway_actor_name to that gateway's FQN. Use a unique client_name per connection; from_ must match client.from_address().

import asyncio
from uuid import uuid4
from pod_os_client import Client, Config
from pod_os_client.message.intents import IntentType
from pod_os_client.message.types import Message

async def main():
    config = Config(
        host="gateway-nlb.example.com",
        port=62312,
        gateway_actor_name="zeroth.customer.example.com",
        client_name=f"my-app-{uuid4().hex[:8]}",
        enable_concurrent_mode=True,
    )
    async with Client(config) as client:
        msg = Message(
            to="Foobar@zeroth.customer.example.com",
            from_=client.from_address(),
            intent=IntentType.GetEvent.name,
            client_name=client.client_name(),
            message_id=str(uuid4()),
        )
        response = await client.send_message(msg)
        print(response.processing_status())

asyncio.run(main())

Configuration highlights

Field Notes
host / port / network TCP dial target (tcp, udp, or unix)
gateway_actor_name Required — FQN of the gateway you dialed
client_name Unique per TCP connection
enable_concurrent_mode Multiple in-flight requests
enable_pooling / pool capacities High-throughput pools
external_receiver App owns connection.receive(); use send_no_wait()
keepalive_interval Default 30s; 0 or negative disables
connection_liveness_timeout Default 90s pending-request backstop

ENM operations

Batch Intents take structured payloads; the encoder formats them (aligned with Go):

from pod_os_client.message import Message, PayloadFields
from pod_os_client.message.intents import IntentType
from pod_os_client.message.types import BatchEventSpec, EventFields, Tag
from uuid import uuid4

batch_msg = Message(
    to="mem@gateway",
    from_="client@gateway",
    intent=IntentType.StoreBatchEvents.name,
    client_name="client",
    message_id=str(uuid4()),
    payload=PayloadFields(
        data=[
            BatchEventSpec(
                event=EventFields(unique_id="ev-1", type="my_type", owner="$sys"),
                tags=[Tag(key="category", value="example", frequency=1)],
            ),
        ],
    ),
)
response = await client.send_message(batch_msg)

StoreData stores raw payload bytes/text without tags. See Add data and Query data for more patterns.

Reading links

GetEvent and GetEventsForTags put Linked on response.event_records[].links. strength is the returned or matched object toward its neighbor (source_unique_id → target_unique_id). StoreBatchLinks and LinkEvent still send LinkFields (strength_a, strength_b). Walkthrough: Query data.

Socket Actor health

from pod_os_client.health import respond_to_health_checks

# enable_concurrent_mode=True required
await client.connect()
respond_to_health_checks(client)

Package layout

  • pod_os_client.client — Client
  • pod_os_client.config — Config
  • pod_os_client.message — encode/decode, types, Intents
  • pod_os_client.connection — TCP/UDP, pooling, retry
  • pod_os_client.errors — exceptions

Related