piopiy-agent 1.0.0__tar.gz

piopiy_agent-1.0.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: piopiy-agent
+Version: 1.0.0
+Summary: Connect a voice agent to the TeleCMI telephony platform
+License: MIT
+Project-URL: Homepage, https://piopiy.com
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio>=1.60
+Requires-Dist: protobuf>=4.25
+
+# piopiy-agent
+
+Connect a voice agent to the TeleCMI telephony platform.
+
+```bash
+pip install piopiy-agent
+```
+
+No `protoc`. No `grpcio-tools`. No protobuf version clash. The stubs ship
+pre-generated, built against an old runtime, so they load under whatever
+protobuf your agent framework pins.
+
+## Check your credentials
+
+```bash
+export PIOPIY_AGENT_ID=agent_42
+export PIOPIY_TOKEN=eyJhbGciOi...
+
+python -m piopiy_agent
+```
+
+A `.env` in the working directory is picked up too, if `python-dotenv` is
+installed.
+
+```
+OK    registered in 41ms
+      accept_deadline_ms 400
+```
+
+Do this before anything else. It separates "my credentials are wrong" from
+"my agent code is wrong", which otherwise look identical.
+
+## Take calls
+
+```python
+import asyncio
+from piopiy_agent import PiopiyWorker
+
+worker = PiopiyWorker(max_sessions=10)
+
+@worker.on_job
+async def handle(job):
+    # Everything needed to join is on the job. The token is pre-minted and
+    # scoped to this one room - you never hold LiveKit admin credentials.
+    await my_agent.join(job.livekit_url, job.access_token, job.room_name)
+
+    # ONLY once you are actually in the room. The caller is bridged in on
+    # the strength of this call.
+    await job.accept()
+
+    await my_agent.run()   # returns when the call ends
+
+asyncio.run(worker.run())
+```
+
+`job.call` carries `from_number`, `to_number`, `direction`, `call_uuid` and any
+whitelisted SIP headers.
+
+## The one rule
+
+**Accept only after you are in the room.**
+
+TeleCMI bridges the caller the moment you accept. Accept on *receiving* the
+job and the caller arrives in an empty room and hears silence — which is the
+single failure this whole design exists to prevent.
+
+You have `job.deadline_ms` (400 by default) to join. `job.remaining_ms` tells
+you what is left.
+
+If you join late, `job.accept()` returns **False** and sends nothing: the call
+has gone to another instance, and a late accept would put two agents on one
+call. Leave the room when you see False.
+
+## What the SDK handles so you do not have to
+
+- **Registration and reconnects.** A TeleCMI restart ends your stream with
+  `CANCELLED`, not `UNAVAILABLE`. `CANCELLED` is non-retryable by gRPC
+  convention, so a client reconnecting only on `UNAVAILABLE` silently stays
+  down after every deploy. This reconnects on any end of stream, with backoff.
+- **Serving late.** Reports `NOT_SERVING` until one call has actually been
+  accepted. A gRPC channel opens long before a Python process can reach a
+  media server, and a fresh instance reports zero active sessions — so it
+  looks like the *best* candidate exactly when it is least able to answer.
+- **Capacity.** Stops accepting at `max_sessions` and rejects with
+  `AT_CAPACITY`. Be honest with this number: a worker that takes more than it
+  can serve produces dead air, where a fast rejection costs TeleCMI 2ms and it
+  moves on.
+- **Heartbeats and status.**
+- **A handler that returns without accepting** is rejected rather than left to
+  time out — the caller is listening to silence for every millisecond of it.
+
+## Configuration
+
+Constructor arguments, or environment:
+
+| | |
+|---|---|
+| `TELECMI_AGENT_ID` | from the dashboard |
+| `TELECMI_TOKEN` | from the dashboard |
+| `PIOPIY_REGISTER` | default `grpc.piopiy.com:50051` |
+| `PIOPIY_TLS` | `false` only against a local register |
+| `TELECMI_INSTANCE_ID` | defaults to hostname-pid |
+
+## Why the stubs are vendored
+
+Generated protobuf code carries the version it was built with, and the runtime
+refuses to load gencode **newer** than itself. `pip install grpcio-tools`
+resolves protobuf 7.x, while agent frameworks commonly pin 5.x — so generating
+locally produces stubs your own environment cannot import:
+
+```
+VersionError: gencode 7.35.1 runtime 5.29.6
+```
+
+The error names protobuf, not gRPC and not TeleCMI, which is what makes it
+expensive to diagnose. Shipping stubs built against an old runtime removes the
+problem: protobuf accepts a runtime newer than the gencode, never older.
+
+Verified against protobuf 4.25, 5.29 and 7.36.

piopiy_agent-1.0.0/README.md

@@ -0,0 +1,119 @@
+# piopiy-agent
+
+Connect a voice agent to the TeleCMI telephony platform.
+
+```bash
+pip install piopiy-agent
+```
+
+No `protoc`. No `grpcio-tools`. No protobuf version clash. The stubs ship
+pre-generated, built against an old runtime, so they load under whatever
+protobuf your agent framework pins.
+
+## Check your credentials
+
+```bash
+export PIOPIY_AGENT_ID=agent_42
+export PIOPIY_TOKEN=eyJhbGciOi...
+
+python -m piopiy_agent
+```
+
+A `.env` in the working directory is picked up too, if `python-dotenv` is
+installed.
+
+```
+OK    registered in 41ms
+      accept_deadline_ms 400
+```
+
+Do this before anything else. It separates "my credentials are wrong" from
+"my agent code is wrong", which otherwise look identical.
+
+## Take calls
+
+```python
+import asyncio
+from piopiy_agent import PiopiyWorker
+
+worker = PiopiyWorker(max_sessions=10)
+
+@worker.on_job
+async def handle(job):
+    # Everything needed to join is on the job. The token is pre-minted and
+    # scoped to this one room - you never hold LiveKit admin credentials.
+    await my_agent.join(job.livekit_url, job.access_token, job.room_name)
+
+    # ONLY once you are actually in the room. The caller is bridged in on
+    # the strength of this call.
+    await job.accept()
+
+    await my_agent.run()   # returns when the call ends
+
+asyncio.run(worker.run())
+```
+
+`job.call` carries `from_number`, `to_number`, `direction`, `call_uuid` and any
+whitelisted SIP headers.
+
+## The one rule
+
+**Accept only after you are in the room.**
+
+TeleCMI bridges the caller the moment you accept. Accept on *receiving* the
+job and the caller arrives in an empty room and hears silence — which is the
+single failure this whole design exists to prevent.
+
+You have `job.deadline_ms` (400 by default) to join. `job.remaining_ms` tells
+you what is left.
+
+If you join late, `job.accept()` returns **False** and sends nothing: the call
+has gone to another instance, and a late accept would put two agents on one
+call. Leave the room when you see False.
+
+## What the SDK handles so you do not have to
+
+- **Registration and reconnects.** A TeleCMI restart ends your stream with
+  `CANCELLED`, not `UNAVAILABLE`. `CANCELLED` is non-retryable by gRPC
+  convention, so a client reconnecting only on `UNAVAILABLE` silently stays
+  down after every deploy. This reconnects on any end of stream, with backoff.
+- **Serving late.** Reports `NOT_SERVING` until one call has actually been
+  accepted. A gRPC channel opens long before a Python process can reach a
+  media server, and a fresh instance reports zero active sessions — so it
+  looks like the *best* candidate exactly when it is least able to answer.
+- **Capacity.** Stops accepting at `max_sessions` and rejects with
+  `AT_CAPACITY`. Be honest with this number: a worker that takes more than it
+  can serve produces dead air, where a fast rejection costs TeleCMI 2ms and it
+  moves on.
+- **Heartbeats and status.**
+- **A handler that returns without accepting** is rejected rather than left to
+  time out — the caller is listening to silence for every millisecond of it.
+
+## Configuration
+
+Constructor arguments, or environment:
+
+| | |
+|---|---|
+| `TELECMI_AGENT_ID` | from the dashboard |
+| `TELECMI_TOKEN` | from the dashboard |
+| `PIOPIY_REGISTER` | default `grpc.piopiy.com:50051` |
+| `PIOPIY_TLS` | `false` only against a local register |
+| `TELECMI_INSTANCE_ID` | defaults to hostname-pid |
+
+## Why the stubs are vendored
+
+Generated protobuf code carries the version it was built with, and the runtime
+refuses to load gencode **newer** than itself. `pip install grpcio-tools`
+resolves protobuf 7.x, while agent frameworks commonly pin 5.x — so generating
+locally produces stubs your own environment cannot import:
+
+```
+VersionError: gencode 7.35.1 runtime 5.29.6
+```
+
+The error names protobuf, not gRPC and not TeleCMI, which is what makes it
+expensive to diagnose. Shipping stubs built against an old runtime removes the
+problem: protobuf accepts a runtime newer than the gencode, never older.
+
+Verified against protobuf 4.25, 5.29 and 7.36.

piopiy_agent-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "piopiy-agent"
+version = "1.0.0"
+description = "Connect a voice agent to the TeleCMI telephony platform"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+
+# grpcio only. The protobuf stubs are PRE-GENERATED and shipped in this
+# package, so nobody installs grpcio-tools and nobody hits the gencode/runtime
+# version clash that comes with generating them locally.
+#
+# protobuf is left unpinned on purpose: the stubs are built against the oldest
+# runtime we support, and protobuf accepts a runtime NEWER than the gencode.
+# Pinning it here would fight whatever the customer's agent framework pins.
+dependencies = [
+    "grpcio>=1.60",
+    "protobuf>=4.25",
+]
+
+[project.urls]
+Homepage = "https://piopiy.com"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+piopiy_agent = ["_pb/*.py"]

piopiy_agent-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

piopiy_agent-1.0.0/src/piopiy_agent/__init__.py

@@ -0,0 +1,22 @@
+"""Connect a voice agent to the TeleCMI telephony platform.
+
+    from piopiy_agent import PiopiyWorker
+
+    worker = PiopiyWorker(agent_id="agent_42", token="...")
+
+    @worker.on_job
+    async def handle(job):
+        await my_agent.join(job.livekit_url, job.access_token, job.room_name)
+        await job.accept()
+        await my_agent.run()
+
+    asyncio.run(worker.run())
+"""
+
+from .job import Call, Job
+from .worker import PiopiyWorker
+
+TeleCMIWorker = PiopiyWorker  # compatibility alias (pre-rename)
+
+__all__ = ["PiopiyWorker", "TeleCMIWorker", "Job", "Call"]
+__version__ = "1.0.0"

piopiy_agent-1.0.0/src/piopiy_agent/__main__.py

@@ -0,0 +1,114 @@
+"""Connectivity and credentials check.
+
+    python -m piopiy_agent
+
+No agent framework, no media server, no API keys - just the TeleCMI handshake.
+Run it first: it separates "my credentials are wrong" from "my agent code is
+wrong", which otherwise produce identical symptoms.
+"""
+
+import asyncio
+import os
+import sys
+import time
+
+import grpc
+
+try:
+    # Optional. Most agent projects keep credentials in a .env, and a check
+    # that silently ignored it would report "not set" for values the customer
+    # can see in their own file.
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ImportError:
+    pass
+
+from ._pb import agent_pb2 as pb
+from ._pb import agent_pb2_grpc as pb_grpc
+
+
+async def check() -> int:
+    register = os.getenv("PIOPIY_REGISTER") or os.getenv("PIOPIY_REGISTER", "grpc.piopiy.com:50051")
+    agent_id = os.getenv("PIOPIY_AGENT_ID") or os.getenv("TELECMI_AGENT_ID", "")
+    token = os.getenv("PIOPIY_TOKEN") or os.getenv("TELECMI_TOKEN", "")
+    tls = (os.getenv("PIOPIY_TLS") or os.getenv("PIOPIY_TLS", "true")).lower() != "false"
+
+    print(f"register  {register}  (tls={tls})")
+    print(f"agent_id  {agent_id or '(not set)'}")
+    print(f"token     {token[:12] + '...' if token else '(not set)'}")
+    print()
+
+    if not agent_id or not token:
+        print("FAIL  set PIOPIY_AGENT_ID and PIOPIY_TOKEN")
+        return 1
+
+    if tls:
+        channel = grpc.aio.secure_channel(register, grpc.ssl_channel_credentials())
+    else:
+        channel = grpc.aio.insecure_channel(register)
+
+    async with channel:
+        stub = pb_grpc.AgentGatewayStub(channel)
+        outbox: asyncio.Queue = asyncio.Queue()
+
+        async def outgoing():
+            while True:
+                message = await outbox.get()
+                if message is None:
+                    return
+                yield message
+
+        started = time.monotonic()
+        stream = stub.Connect(outgoing(), metadata=(("authorization", f"Bearer {token}"),))
+
+        await outbox.put(pb.WorkerMessage(register=pb.Register(
+            agent_id=agent_id,
+            instance_id="connectivity-check",
+            max_sessions=1,
+            runtime="piopiy_agent.check",
+        )))
+
+        try:
+            async for message in stream:
+                if message.WhichOneof("payload") == "registered":
+                    took = int((time.monotonic() - started) * 1000)
+                    print(f"OK    registered in {took}ms")
+                    print(f"      accept_deadline_ms {message.registered.accept_deadline_ms}")
+                    print(f"      heartbeat every    {message.registered.heartbeat_interval_s}s")
+                    print()
+                    print("Credentials work and the register is reachable.")
+                    await outbox.put(None)
+                    return 0
+        except grpc.aio.AioRpcError as err:
+            code = err.code().name
+            print(f"FAIL  {code}: {err.details()}")
+            print()
+            if code == "PERMISSION_DENIED":
+                print("The token and agent_id do not go together. Either the token")
+                print("is not valid, or it belongs to an org that does not own this")
+                print("agent. Both are issued together in the dashboard.")
+            elif code == "UNAVAILABLE":
+                details = err.details() or ""
+                if "WRONG_VERSION_NUMBER" in details or "TSI_PROTOCOL_FAILURE" in details:
+                    # Speaking TLS to a plaintext port. The raw error names
+                    # OpenSSL and a certificate context, neither of which is
+                    # the problem, so say what actually is.
+                    print("The register is not speaking TLS on that port.")
+                    print()
+                    print("    PIOPIY_TLS=false python -m piopiy_agent")
+                    print()
+                    print("Use TLS only against a register that terminates it.")
+                elif "CERTIFICATE_VERIFY_FAILED" in details or "certificate" in details.lower():
+                    print("TLS connected but the certificate was not trusted. Check the")
+                    print("hostname matches the certificate, and that the CA is trusted.")
+                else:
+                    print("Could not reach the register. Check the address, and whether")
+                    print("PIOPIY_TLS matches what the server expects.")
+            return 1
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(check()))

piopiy_agent-1.0.0/src/piopiy_agent/_pb/agent_pb2.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: telecmi/agent/v1/agent.proto
+# Protobuf Python Version: 4.25.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1ctelecmi/agent/v1/agent.proto\x12\x10telecmi.agent.v1\"\xc9\x02\n\rWorkerMessage\x12.\n\x08register\x18\x01 \x01(\x0b\x32\x1a.telecmi.agent.v1.RegisterH\x00\x12\x30\n\x06status\x18\x02 \x01(\x0b\x32\x1e.telecmi.agent.v1.StatusUpdateH\x00\x12\x31\n\x08\x61\x63\x63\x65pted\x18\x03 \x01(\x0b\x32\x1d.telecmi.agent.v1.JobAcceptedH\x00\x12\x31\n\x08rejected\x18\x04 \x01(\x0b\x32\x1d.telecmi.agent.v1.JobRejectedH\x00\x12\x33\n\tcompleted\x18\x05 \x01(\x0b\x32\x1e.telecmi.agent.v1.JobCompletedH\x00\x12\x30\n\theartbeat\x18\x06 \x01(\x0b\x32\x1b.telecmi.agent.v1.HeartbeatH\x00\x42\t\n\x07payload\"\xd0\x01\n\x08Register\x12\x10\n\x08\x61gent_id\x18\x01 \x01(\t\x12\x0f\n\x07\x61pi_key\x18\x02 \x01(\t\x12\x13\n\x0binstance_id\x18\x03 \x01(\t\x12\x14\n\x0cmax_sessions\x18\x04 \x01(\r\x12\x0f\n\x07runtime\x18\x05 \x01(\t\x12\x36\n\x06labels\x18\x06 \x03(\x0b\x32&.telecmi.agent.v1.Register.LabelsEntry\x1a-\n\x0bLabelsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"\x7f\n\x0cStatusUpdate\x12\x17\n\x0f\x61\x63tive_sessions\x18\x01 \x01(\r\x12\x17\n\x0f\x61vailable_slots\x18\x02 \x01(\r\x12-\n\x05state\x18\x03 \x01(\x0e\x32\x1e.telecmi.agent.v1.ServingState\x12\x0e\n\x06\x64\x65tail\x18\x04 \x01(\t\"_\n\x0bJobAccepted\x12\x0e\n\x06job_id\x18\x01 \x01(\t\x12\x11\n\troom_name\x18\x02 \x01(\t\x12\x1c\n\x14participant_identity\x18\x03 \x01(\t\x12\x0f\n\x07join_ms\x18\x04 \x01(\r\"]\n\x0bJobRejected\x12\x0e\n\x06job_id\x18\x01 \x01(\t\x12.\n\x06reason\x18\x02 \x01(\x0e\x32\x1e.telecmi.agent.v1.RejectReason\x12\x0e\n\x06\x64\x65tail\x18\x03 \x01(\t\"R\n\x0cJobCompleted\x12\x0e\n\x06job_id\x18\x01 \x01(\t\x12\x13\n\x0b\x64uration_ms\x18\x02 \x01(\r\x12\r\n\x05\x65rror\x18\x03 \x01(\x08\x12\x0e\n\x06\x64\x65tail\x18\x04 \x01(\t\"!\n\tHeartbeat\x12\x14\n\x0csent_unix_ms\x18\x01 \x01(\x04\"\x8d\x02\n\x11\x44ispatcherMessage\x12\x32\n\nregistered\x18\x01 \x01(\x0b\x32\x1c.telecmi.agent.v1.RegisteredH\x00\x12.\n\x03job\x18\x02 \x01(\x0b\x32\x1f.telecmi.agent.v1.JobAssignmentH\x00\x12-\n\x06\x63\x61ncel\x18\x03 \x01(\x0b\x32\x1b.telecmi.agent.v1.JobCancelH\x00\x12(\n\x05\x64rain\x18\x04 \x01(\x0b\x32\x17.telecmi.agent.v1.DrainH\x00\x12\x30\n\x06hb_ack\x18\x05 \x01(\x0b\x32\x1e.telecmi.agent.v1.HeartbeatAckH\x00\x42\t\n\x07payload\"Z\n\nRegistered\x12\x12\n\nsession_id\x18\x01 \x01(\t\x12\x1c\n\x14heartbeat_interval_s\x18\x02 \x01(\r\x12\x1a\n\x12\x61\x63\x63\x65pt_deadline_ms\x18\x03 \x01(\r\"\xb8\x01\n\rJobAssignment\x12\x0e\n\x06job_id\x18\x01 \x01(\t\x12\x11\n\troom_name\x18\x02 \x01(\t\x12\x13\n\x0blivekit_url\x18\x03 \x01(\t\x12\x14\n\x0c\x61\x63\x63\x65ss_token\x18\x04 \x01(\t\x12\x1a\n\x12\x61\x63\x63\x65pt_deadline_ms\x18\x05 \x01(\r\x12+\n\x04\x63\x61ll\x18\x06 \x01(\x0b\x32\x1d.telecmi.agent.v1.CallContext\x12\x10\n\x08trace_id\x18\x07 \x01(\t\"\xc5\x02\n\x0b\x43\x61llContext\x12\x11\n\tcall_uuid\x18\x01 \x01(\t\x12\x13\n\x0b\x66rom_number\x18\x02 \x01(\t\x12\x11\n\tto_number\x18\x03 \x01(\t\x12\x11\n\tdirection\x18\x04 \x01(\t\x12\x42\n\x0bsip_headers\x18\x05 \x03(\x0b\x32-.telecmi.agent.v1.CallContext.SipHeadersEntry\x12?\n\tvariables\x18\x06 \x03(\x0b\x32,.telecmi.agent.v1.CallContext.VariablesEntry\x1a\x31\n\x0fSipHeadersEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\x1a\x30\n\x0eVariablesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"+\n\tJobCancel\x12\x0e\n\x06job_id\x18\x01 \x01(\t\x12\x0e\n\x06reason\x18\x02 \x01(\t\"\x1e\n\x05\x44rain\x12\x15\n\rgrace_seconds\x18\x01 \x01(\r\"$\n\x0cHeartbeatAck\x12\x14\n\x0csent_unix_ms\x18\x01 \x01(\x04*Y\n\x0cServingState\x12\x1d\n\x19SERVING_STATE_UNSPECIFIED\x10\x00\x12\x0b\n\x07SERVING\x10\x01\x12\x0c\n\x08\x44RAINING\x10\x02\x12\x0f\n\x0bNOT_SERVING\x10\x03*y\n\x0cRejectReason\x12\x1d\n\x19REJECT_REASON_UNSPECIFIED\x10\x00\x12\x0f\n\x0b\x41T_CAPACITY\x10\x01\x12\x14\n\x10ROOM_JOIN_FAILED\x10\x02\x12\x10\n\x0c\x43ONFIG_ERROR\x10\x03\x12\x11\n\rSHUTTING_DOWN\x10\x04\x32\x63\n\x0c\x41gentGateway\x12S\n\x07\x43onnect\x12\x1f.telecmi.agent.v1.WorkerMessage\x1a#.telecmi.agent.v1.DispatcherMessage(\x01\x30\x01\x42X\n\x14\x63om.telecmi.agent.v1P\x01Z>github.com/telecmi/agent-proto/gen/go/telecmi/agent/v1;agentv1b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'telecmi.agent.v1.agent_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  _globals['DESCRIPTOR']._options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\n\024com.telecmi.agent.v1P\001Z>github.com/telecmi/agent-proto/gen/go/telecmi/agent/v1;agentv1'
+  _globals['_REGISTER_LABELSENTRY']._options = None
+  _globals['_REGISTER_LABELSENTRY']._serialized_options = b'8\001'
+  _globals['_CALLCONTEXT_SIPHEADERSENTRY']._options = None
+  _globals['_CALLCONTEXT_SIPHEADERSENTRY']._serialized_options = b'8\001'
+  _globals['_CALLCONTEXT_VARIABLESENTRY']._options = None
+  _globals['_CALLCONTEXT_VARIABLESENTRY']._serialized_options = b'8\001'
+  _globals['_SERVINGSTATE']._serialized_start=2027
+  _globals['_SERVINGSTATE']._serialized_end=2116
+  _globals['_REJECTREASON']._serialized_start=2118
+  _globals['_REJECTREASON']._serialized_end=2239
+  _globals['_WORKERMESSAGE']._serialized_start=51
+  _globals['_WORKERMESSAGE']._serialized_end=380
+  _globals['_REGISTER']._serialized_start=383
+  _globals['_REGISTER']._serialized_end=591
+  _globals['_REGISTER_LABELSENTRY']._serialized_start=546
+  _globals['_REGISTER_LABELSENTRY']._serialized_end=591
+  _globals['_STATUSUPDATE']._serialized_start=593
+  _globals['_STATUSUPDATE']._serialized_end=720
+  _globals['_JOBACCEPTED']._serialized_start=722
+  _globals['_JOBACCEPTED']._serialized_end=817
+  _globals['_JOBREJECTED']._serialized_start=819
+  _globals['_JOBREJECTED']._serialized_end=912
+  _globals['_JOBCOMPLETED']._serialized_start=914
+  _globals['_JOBCOMPLETED']._serialized_end=996
+  _globals['_HEARTBEAT']._serialized_start=998
+  _globals['_HEARTBEAT']._serialized_end=1031
+  _globals['_DISPATCHERMESSAGE']._serialized_start=1034
+  _globals['_DISPATCHERMESSAGE']._serialized_end=1303
+  _globals['_REGISTERED']._serialized_start=1305
+  _globals['_REGISTERED']._serialized_end=1395
+  _globals['_JOBASSIGNMENT']._serialized_start=1398
+  _globals['_JOBASSIGNMENT']._serialized_end=1582
+  _globals['_CALLCONTEXT']._serialized_start=1585
+  _globals['_CALLCONTEXT']._serialized_end=1910
+  _globals['_CALLCONTEXT_SIPHEADERSENTRY']._serialized_start=1811
+  _globals['_CALLCONTEXT_SIPHEADERSENTRY']._serialized_end=1860
+  _globals['_CALLCONTEXT_VARIABLESENTRY']._serialized_start=1862
+  _globals['_CALLCONTEXT_VARIABLESENTRY']._serialized_end=1910
+  _globals['_JOBCANCEL']._serialized_start=1912
+  _globals['_JOBCANCEL']._serialized_end=1955
+  _globals['_DRAIN']._serialized_start=1957
+  _globals['_DRAIN']._serialized_end=1987
+  _globals['_HEARTBEATACK']._serialized_start=1989
+  _globals['_HEARTBEATACK']._serialized_end=2025
+  _globals['_AGENTGATEWAY']._serialized_start=2241
+  _globals['_AGENTGATEWAY']._serialized_end=2340
+# @@protoc_insertion_point(module_scope)

piopiy_agent-1.0.0/src/piopiy_agent/_pb/agent_pb2_grpc.py

@@ -0,0 +1,88 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+
+from . import agent_pb2 as telecmi_dot_agent_dot_v1_dot_agent__pb2
+
+
+class AgentGatewayStub(object):
+    """AgentGateway is the contract between the TeleCMI dispatcher and a
+    customer-operated voice agent runtime (Pipecat, LiveKit Agents, or custom).
+
+    The worker connects OUT to us and holds the stream open. We never connect to
+    the worker, so customers do not need inbound firewall rules or public IPs.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Connect = channel.stream_stream(
+                '/telecmi.agent.v1.AgentGateway/Connect',
+                request_serializer=telecmi_dot_agent_dot_v1_dot_agent__pb2.WorkerMessage.SerializeToString,
+                response_deserializer=telecmi_dot_agent_dot_v1_dot_agent__pb2.DispatcherMessage.FromString,
+                )
+
+
+class AgentGatewayServicer(object):
+    """AgentGateway is the contract between the TeleCMI dispatcher and a
+    customer-operated voice agent runtime (Pipecat, LiveKit Agents, or custom).
+
+    The worker connects OUT to us and holds the stream open. We never connect to
+    the worker, so customers do not need inbound firewall rules or public IPs.
+    """
+
+    def Connect(self, request_iterator, context):
+        """Long-lived bidirectional stream. The worker opens it at startup and holds
+        it for the life of the process.
+
+        Authentication is per-RPC metadata: `authorization: Bearer <api_key>`,
+        validated when the stream opens. A key maps to exactly one
+        {tenant_id, agent_id}; registering with an agent_id the key does not own
+        fails with PERMISSION_DENIED.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_AgentGatewayServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Connect': grpc.stream_stream_rpc_method_handler(
+                    servicer.Connect,
+                    request_deserializer=telecmi_dot_agent_dot_v1_dot_agent__pb2.WorkerMessage.FromString,
+                    response_serializer=telecmi_dot_agent_dot_v1_dot_agent__pb2.DispatcherMessage.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'telecmi.agent.v1.AgentGateway', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+
+
+ # This class is part of an EXPERIMENTAL API.
+class AgentGateway(object):
+    """AgentGateway is the contract between the TeleCMI dispatcher and a
+    customer-operated voice agent runtime (Pipecat, LiveKit Agents, or custom).
+
+    The worker connects OUT to us and holds the stream open. We never connect to
+    the worker, so customers do not need inbound firewall rules or public IPs.
+    """
+
+    @staticmethod
+    def Connect(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(request_iterator, target, '/telecmi.agent.v1.AgentGateway/Connect',
+            telecmi_dot_agent_dot_v1_dot_agent__pb2.WorkerMessage.SerializeToString,
+            telecmi_dot_agent_dot_v1_dot_agent__pb2.DispatcherMessage.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

piopiy_agent-1.0.0/src/piopiy_agent/job.py

@@ -0,0 +1,94 @@
+"""One call, offered to this worker."""
+
+import time
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+
+@dataclass(frozen=True)
+class Call:
+    """Who is calling, and who they dialled."""
+
+    call_uuid: str
+    from_number: str
+    to_number: str
+    direction: str
+    sip_headers: Dict[str, str]
+    variables: Dict[str, str]
+
+
+class Job:
+    """A call offered to you. Join the room, then accept.
+
+    Everything needed to join is here: `livekit_url`, `access_token` and
+    `room_name`. The token is pre-minted and scoped to this one room, so you
+    never hold LiveKit admin credentials.
+
+    The caller is bridged in the moment you accept, so accept only once you are
+    ACTUALLY in the room. Accept early and they arrive to silence.
+    """
+
+    def __init__(self, message, worker, *, deadline_ms: int):
+        self.job_id: str = message.job_id
+        self.room_name: str = message.room_name
+        self.livekit_url: str = message.livekit_url
+        self.access_token: str = message.access_token
+        self.trace_id: str = message.trace_id
+
+        self.call = Call(
+            call_uuid=message.call.call_uuid,
+            from_number=message.call.from_number,
+            to_number=message.call.to_number,
+            direction=message.call.direction,
+            sip_headers=dict(message.call.sip_headers),
+            variables=dict(message.call.variables),
+        )
+
+        self._worker = worker
+        self._deadline_ms = deadline_ms
+        self._offered_at = time.monotonic()
+        self._settled = False
+
+    @property
+    def deadline_ms(self) -> int:
+        """How long you have to join and accept."""
+        return self._deadline_ms
+
+    @property
+    def remaining_ms(self) -> int:
+        """Time left before this offer expires."""
+        spent = (time.monotonic() - self._offered_at) * 1000
+        return max(0, int(self._deadline_ms - spent))
+
+    @property
+    def settled(self) -> bool:
+        return self._settled
+
+    async def accept(self, *, participant_identity: Optional[str] = None) -> bool:
+        """Tell TeleCMI you are in the room. Call this AFTER joining.
+
+        Returns False if the deadline has already passed - in which case the
+        call has gone to another instance and you must leave the room. The SDK
+        will not send a late accept, because that is how two agents end up on
+        one call.
+        """
+        if self._settled:
+            return False
+
+        join_ms = int((time.monotonic() - self._offered_at) * 1000)
+
+        if join_ms > self._deadline_ms:
+            self._settled = True
+            await self._worker._on_late_join(self, join_ms)
+            return False
+
+        self._settled = True
+        await self._worker._send_accepted(self, join_ms, participant_identity)
+        return True
+
+    async def reject(self, reason: str = "AT_CAPACITY", detail: str = "") -> None:
+        """Decline it. A fast, honest no is cheap; silence costs the caller."""
+        if self._settled:
+            return
+        self._settled = True
+        await self._worker._send_rejected(self, reason, detail)

piopiy_agent-1.0.0/src/piopiy_agent/worker.py

@@ -0,0 +1,295 @@
+"""The TeleCMI worker: connect, register, take calls."""
+
+import asyncio
+import logging
+import os
+import socket
+import time
+from typing import Awaitable, Callable, Dict, Optional
+
+import grpc
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ImportError:
+    pass
+
+from ._pb import agent_pb2 as pb
+from ._pb import agent_pb2_grpc as pb_grpc
+from .job import Job
+
+log = logging.getLogger("piopiy_agent")
+
+JobHandler = Callable[[Job], Awaitable[None]]
+
+# Transport keepalive is how TeleCMI notices a wedged process that is still
+# holding its TCP connection. Heartbeat carries capacity, not liveness.
+_CHANNEL_OPTIONS = [
+    ("grpc.keepalive_time_ms", 10_000),
+    ("grpc.keepalive_timeout_ms", 20_000),
+    ("grpc.keepalive_permit_without_calls", 0),
+]
+
+
+class PiopiyWorker:
+    """Connects out to TeleCMI and holds one long-lived stream.
+
+    TeleCMI never connects to you, so no inbound firewall rules and no public
+    IP are needed.
+
+        worker = PiopiyWorker(agent_id=..., token=...)
+
+        @worker.on_job
+        async def handle(job):
+            await my_agent.join(job.livekit_url, job.access_token, job.room_name)
+            await job.accept()          # only once you are IN the room
+            await my_agent.run()        # returns when the call ends
+
+        asyncio.run(worker.run())
+
+    The SDK handles registration, heartbeats, capacity reporting, reconnects
+    and the accept deadline. You handle the call.
+    """
+
+    def __init__(
+        self,
+        *,
+        agent_id: Optional[str] = None,
+        token: Optional[str] = None,
+        register: Optional[str] = None,
+        max_sessions: int = 10,
+        instance_id: Optional[str] = None,
+        tls: Optional[bool] = None,
+        runtime: str = "piopiy-agent-python/1.0.0",
+        labels: Optional[Dict[str, str]] = None,
+    ):
+        self.agent_id = agent_id or os.environ.get("PIOPIY_AGENT_ID") or os.environ["TELECMI_AGENT_ID"]
+        self.token = token or os.environ.get("PIOPIY_TOKEN") or os.environ["TELECMI_TOKEN"]
+        self.register = register or os.getenv("PIOPIY_REGISTER") or os.getenv("PIOPIY_REGISTER", "grpc.piopiy.com:50051")
+        self.max_sessions = max_sessions
+        self.instance_id = instance_id or (os.getenv("PIOPIY_INSTANCE_ID") or os.getenv("TELECMI_INSTANCE_ID")) \
+            or f"{socket.gethostname()}-{os.getpid()}"
+        self.runtime = runtime
+        self.labels = labels or {}
+
+        if tls is None:
+            tls = (os.getenv("PIOPIY_TLS") or os.getenv("PIOPIY_TLS", "true")).lower() != "false"
+        self.tls = tls
+
+        self._handler: Optional[JobHandler] = None
+        self._outbox: asyncio.Queue = asyncio.Queue()
+        self._active: Dict[str, Job] = {}
+        self._tasks: Dict[str, asyncio.Task] = {}
+        self._draining = False
+
+        # False until one call has actually been accepted. A gRPC channel opens
+        # long before a Python process can reach a media server, and a fresh
+        # instance reports zero active sessions - so it looks like the BEST
+        # candidate exactly when it is least able to answer. Reporting
+        # NOT_SERVING until proven is what stops that.
+        self._proven = False
+
+        self._accept_deadline_ms = 400
+        self._heartbeat_s = 10
+
+    # ---------- registration ----------
+
+    def on_job(self, handler: JobHandler) -> JobHandler:
+        """Register the coroutine that handles a call."""
+        self._handler = handler
+        return handler
+
+    async def run(self) -> None:
+        """Connect and serve until stopped. Reconnects on its own."""
+        if self._handler is None:
+            raise RuntimeError("no job handler registered - use @worker.on_job")
+
+        backoff = 1
+        while True:
+            try:
+                await self._session()
+                backoff = 1
+            except grpc.aio.AioRpcError as err:
+                # A TeleCMI restart ends the stream with CANCELLED, not
+                # UNAVAILABLE. CANCELLED is non-retryable by gRPC convention,
+                # so a client that reconnects only on UNAVAILABLE stays down
+                # after every deploy. Reconnect on any end of stream.
+                log.warning("stream ended: %s %s", err.code().name, err.details())
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                log.exception("session failed")
+
+            if self._draining and not self._active:
+                log.info("drained, stopping")
+                return
+
+            log.info("reconnecting in %ss", backoff)
+            await asyncio.sleep(backoff)
+            backoff = min(backoff * 2, 30)
+
+    async def _session(self) -> None:
+        if self.tls:
+            channel = grpc.aio.secure_channel(
+                self.register, grpc.ssl_channel_credentials(), options=_CHANNEL_OPTIONS
+            )
+        else:
+            channel = grpc.aio.insecure_channel(self.register, options=_CHANNEL_OPTIONS)
+
+        async with channel:
+            stub = pb_grpc.AgentGatewayStub(channel)
+            # The token goes in metadata; the api_key field on Register exists
+            # only for early clients.
+            metadata = (("authorization", f"Bearer {self.token}"),)
+            stream = stub.Connect(self._outgoing(), metadata=metadata)
+
+            await self._send(pb.WorkerMessage(register=pb.Register(
+                agent_id=self.agent_id,
+                instance_id=self.instance_id,
+                max_sessions=self.max_sessions,
+                runtime=self.runtime,
+                labels=self.labels,
+            )))
+
+            heartbeat: Optional[asyncio.Task] = None
+            try:
+                async for message in stream:
+                    kind = message.WhichOneof("payload")
+
+                    if kind == "registered":
+                        self._accept_deadline_ms = message.registered.accept_deadline_ms or 400
+                        self._heartbeat_s = message.registered.heartbeat_interval_s or 10
+                        log.info(
+                            "registered as %s (accept deadline %sms)",
+                            self.instance_id, self._accept_deadline_ms,
+                        )
+                        heartbeat = asyncio.create_task(self._heartbeat_loop())
+
+                    elif kind == "job":
+                        self._tasks[message.job.job_id] = asyncio.create_task(
+                            self._run_job(message.job)
+                        )
+
+                    elif kind == "cancel":
+                        await self._cancel(message.cancel.job_id, message.cancel.reason)
+
+                    elif kind == "drain":
+                        log.info("draining (%ss grace)", message.drain.grace_seconds)
+                        self._draining = True
+                        await self._send_status()
+            finally:
+                if heartbeat:
+                    heartbeat.cancel()
+
+    async def _outgoing(self):
+        while True:
+            message = await self._outbox.get()
+            if message is None:
+                return
+            yield message
+
+    async def _send(self, message) -> None:
+        await self._outbox.put(message)
+
+    # ---------- the call ----------
+
+    async def _run_job(self, message) -> None:
+        job = Job(message, self, deadline_ms=message.accept_deadline_ms or self._accept_deadline_ms)
+
+        if self._draining or len(self._active) >= self.max_sessions:
+            reason = "SHUTTING_DOWN" if self._draining else "AT_CAPACITY"
+            await job.reject(reason)
+            return
+
+        self._active[job.job_id] = job
+        started = time.monotonic()
+
+        try:
+            await self._handler(job)
+        except asyncio.CancelledError:
+            raise
+        except Exception as err:
+            log.exception("handler failed for %s", job.job_id)
+            if not job.settled:
+                await job.reject("ROOM_JOIN_FAILED", str(err)[:200])
+            return
+        finally:
+            self._active.pop(job.job_id, None)
+            self._tasks.pop(job.job_id, None)
+
+        if not job.settled:
+            # The handler returned without ever accepting. TeleCMI is still
+            # waiting, so say no rather than letting the deadline expire - the
+            # caller is listening to silence for every millisecond of it.
+            log.warning("handler returned without accepting %s", job.job_id)
+            await job.reject("CONFIG_ERROR", "handler did not accept")
+            return
+
+        await self._send(pb.WorkerMessage(completed=pb.JobCompleted(
+            job_id=job.job_id,
+            duration_ms=int((time.monotonic() - started) * 1000),
+        )))
+        await self._send_status()
+
+    async def _cancel(self, job_id: str, reason: str) -> None:
+        log.info("cancelled %s: %s", job_id, reason)
+        task = self._tasks.pop(job_id, None)
+        self._active.pop(job_id, None)
+        if task:
+            task.cancel()
+        await self._send_status()
+
+    # ---------- protocol, called by Job ----------
+
+    async def _send_accepted(self, job: Job, join_ms: int, identity: Optional[str]) -> None:
+        self._proven = True
+        await self._send(pb.WorkerMessage(accepted=pb.JobAccepted(
+            job_id=job.job_id,
+            room_name=job.room_name,
+            participant_identity=identity or "",
+            join_ms=join_ms,
+        )))
+        await self._send_status()
+
+    async def _send_rejected(self, job: Job, reason: str, detail: str) -> None:
+        await self._send(pb.WorkerMessage(rejected=pb.JobRejected(
+            job_id=job.job_id,
+            reason=getattr(pb, reason, pb.REJECT_REASON_UNSPECIFIED),
+            detail=detail,
+        )))
+
+    async def _on_late_join(self, job: Job, join_ms: int) -> None:
+        # Past the deadline TeleCMI has already offered this call elsewhere.
+        # Accepting now would put two agents in one room, so we do not send it.
+        log.warning(
+            "joined %s after the deadline (%sms > %sms) - leave the room",
+            job.job_id, join_ms, job.deadline_ms,
+        )
+
+    # ---------- health ----------
+
+    async def _heartbeat_loop(self) -> None:
+        while True:
+            await self._send(pb.WorkerMessage(
+                heartbeat=pb.Heartbeat(sent_unix_ms=int(time.time() * 1000))
+            ))
+            await self._send_status()
+            await asyncio.sleep(self._heartbeat_s)
+
+    async def _send_status(self) -> None:
+        # SERVING even before the first call. Reporting NOT_SERVING while
+        # merely starting up conflates "new" with "broken", and TeleCMI cannot
+        # tell them apart - so a fleet where nothing has proven itself yet
+        # would never be offered a call, and could never prove itself.
+        #
+        # TeleCMI tracks proven-ness on its own side and sorts warm instances
+        # ahead of cold ones. Serving late is its job, not ours.
+        state = pb.DRAINING if self._draining else pb.SERVING
+
+        await self._send(pb.WorkerMessage(status=pb.StatusUpdate(
+            active_sessions=len(self._active),
+            available_slots=max(0, self.max_sessions - len(self._active)),
+            state=state,
+        )))

piopiy_agent-1.0.0/src/piopiy_agent.egg-info/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: piopiy-agent
+Version: 1.0.0
+Summary: Connect a voice agent to the TeleCMI telephony platform
+License: MIT
+Project-URL: Homepage, https://piopiy.com
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio>=1.60
+Requires-Dist: protobuf>=4.25
+
+# piopiy-agent
+
+Connect a voice agent to the TeleCMI telephony platform.
+
+```bash
+pip install piopiy-agent
+```
+
+No `protoc`. No `grpcio-tools`. No protobuf version clash. The stubs ship
+pre-generated, built against an old runtime, so they load under whatever
+protobuf your agent framework pins.
+
+## Check your credentials
+
+```bash
+export PIOPIY_AGENT_ID=agent_42
+export PIOPIY_TOKEN=eyJhbGciOi...
+
+python -m piopiy_agent
+```
+
+A `.env` in the working directory is picked up too, if `python-dotenv` is
+installed.
+
+```
+OK    registered in 41ms
+      accept_deadline_ms 400
+```
+
+Do this before anything else. It separates "my credentials are wrong" from
+"my agent code is wrong", which otherwise look identical.
+
+## Take calls
+
+```python
+import asyncio
+from piopiy_agent import PiopiyWorker
+
+worker = PiopiyWorker(max_sessions=10)
+
+@worker.on_job
+async def handle(job):
+    # Everything needed to join is on the job. The token is pre-minted and
+    # scoped to this one room - you never hold LiveKit admin credentials.
+    await my_agent.join(job.livekit_url, job.access_token, job.room_name)
+
+    # ONLY once you are actually in the room. The caller is bridged in on
+    # the strength of this call.
+    await job.accept()
+
+    await my_agent.run()   # returns when the call ends
+
+asyncio.run(worker.run())
+```
+
+`job.call` carries `from_number`, `to_number`, `direction`, `call_uuid` and any
+whitelisted SIP headers.
+
+## The one rule
+
+**Accept only after you are in the room.**
+
+TeleCMI bridges the caller the moment you accept. Accept on *receiving* the
+job and the caller arrives in an empty room and hears silence — which is the
+single failure this whole design exists to prevent.
+
+You have `job.deadline_ms` (400 by default) to join. `job.remaining_ms` tells
+you what is left.
+
+If you join late, `job.accept()` returns **False** and sends nothing: the call
+has gone to another instance, and a late accept would put two agents on one
+call. Leave the room when you see False.
+
+## What the SDK handles so you do not have to
+
+- **Registration and reconnects.** A TeleCMI restart ends your stream with
+  `CANCELLED`, not `UNAVAILABLE`. `CANCELLED` is non-retryable by gRPC
+  convention, so a client reconnecting only on `UNAVAILABLE` silently stays
+  down after every deploy. This reconnects on any end of stream, with backoff.
+- **Serving late.** Reports `NOT_SERVING` until one call has actually been
+  accepted. A gRPC channel opens long before a Python process can reach a
+  media server, and a fresh instance reports zero active sessions — so it
+  looks like the *best* candidate exactly when it is least able to answer.
+- **Capacity.** Stops accepting at `max_sessions` and rejects with
+  `AT_CAPACITY`. Be honest with this number: a worker that takes more than it
+  can serve produces dead air, where a fast rejection costs TeleCMI 2ms and it
+  moves on.
+- **Heartbeats and status.**
+- **A handler that returns without accepting** is rejected rather than left to
+  time out — the caller is listening to silence for every millisecond of it.
+
+## Configuration
+
+Constructor arguments, or environment:
+
+| | |
+|---|---|
+| `TELECMI_AGENT_ID` | from the dashboard |
+| `TELECMI_TOKEN` | from the dashboard |
+| `PIOPIY_REGISTER` | default `grpc.piopiy.com:50051` |
+| `PIOPIY_TLS` | `false` only against a local register |
+| `TELECMI_INSTANCE_ID` | defaults to hostname-pid |
+
+## Why the stubs are vendored
+
+Generated protobuf code carries the version it was built with, and the runtime
+refuses to load gencode **newer** than itself. `pip install grpcio-tools`
+resolves protobuf 7.x, while agent frameworks commonly pin 5.x — so generating
+locally produces stubs your own environment cannot import:
+
+```
+VersionError: gencode 7.35.1 runtime 5.29.6
+```
+
+The error names protobuf, not gRPC and not TeleCMI, which is what makes it
+expensive to diagnose. Shipping stubs built against an old runtime removes the
+problem: protobuf accepts a runtime newer than the gencode, never older.
+
+Verified against protobuf 4.25, 5.29 and 7.36.

piopiy_agent-1.0.0/src/piopiy_agent.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/piopiy_agent/__init__.py
+src/piopiy_agent/__main__.py
+src/piopiy_agent/job.py
+src/piopiy_agent/worker.py
+src/piopiy_agent.egg-info/PKG-INFO
+src/piopiy_agent.egg-info/SOURCES.txt
+src/piopiy_agent.egg-info/dependency_links.txt
+src/piopiy_agent.egg-info/requires.txt
+src/piopiy_agent.egg-info/top_level.txt
+src/piopiy_agent/_pb/__init__.py
+src/piopiy_agent/_pb/agent_pb2.py
+src/piopiy_agent/_pb/agent_pb2_grpc.py
+src/telecmi_agent/__init__.py

piopiy_agent-1.0.0/src/piopiy_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

piopiy_agent-1.0.0/src/piopiy_agent.egg-info/requires.txt

@@ -0,0 +1,2 @@
+grpcio>=1.60
+protobuf>=4.25

piopiy_agent-1.0.0/src/piopiy_agent.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+piopiy_agent
+telecmi_agent

piopiy_agent-1.0.0/src/telecmi_agent/__init__.py

@@ -0,0 +1,13 @@
+"""Compatibility shim: the package is now `piopiy_agent`. This import path
+keeps pre-rename code working and will be removed in 2.0."""
+
+import warnings
+
+from piopiy_agent import Call, Job, PiopiyWorker
+from piopiy_agent import __version__
+
+TeleCMIWorker = PiopiyWorker
+
+warnings.warn("telecmi_agent is now piopiy_agent - update your import", DeprecationWarning, stacklevel=2)
+
+__all__ = ["TeleCMIWorker", "PiopiyWorker", "Job", "Call", "__version__"]