signalcore 0.1.0__tar.gz

signalcore-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+
+# Node
+node_modules/
+.next/
+out/
+.turbo/
+
+# Env & secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# OS / editors
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/*
+!.vscode/extensions.json
+
+# Terraform / OpenTofu (plans and state can contain secrets; the lock file IS committed)
+.terraform/
+*.tfplan
+*.tfstate
+*.tfstate.*
+crash.log
+
+# Local object storage (SC_FILES_DIR)
+.files/

signalcore-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SignalCore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

signalcore-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: signalcore
+Version: 0.1.0
+Summary: The Python client for SignalCore: create agents, talk to them and run everything around them.
+Project-URL: Homepage, https://signalcore.ai
+Project-URL: Documentation, https://signalcore.ai/docs
+Project-URL: Repository, https://github.com/OmnistGroup/signalcore/tree/staging/clients/python
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,api,sdk,signalcore
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.5
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# signalcore
+
+The Python client for [SignalCore](https://signalcore.ai): create agents, talk to them, and run
+everything around them (conversations, approvals, knowledge, records, apps) from your own code.
+
+```bash
+pip install signalcore
+```
+
+Python 3.11 or newer. Create an API key in the web app and export it:
+
+```bash
+export SIGNALCORE_API_KEY=sk_live_...
+```
+
+## Quickstart
+
+```python
+import asyncio
+
+from signalcore import AsyncSignalcore
+
+
+async def main() -> None:
+    async with AsyncSignalcore() as client:  # reads SIGNALCORE_API_KEY
+        agent = await client.agents.create("Reception", instructions="You answer for Clínica Sol.")
+        await client.agents.publish(agent.id)
+
+        answer = await client.agents.invoke(
+            agent.id, input="Do you open on Saturdays?", thread="ticket-7"
+        )
+        print(answer.text)
+
+        async for event in client.runs.stream(answer.run_id):  # the run's journal, live
+            print(event.event, event.json())
+
+
+asyncio.run(main())
+```
+
+Code that does not use `asyncio` imports `Signalcore` instead: the same client, same names,
+no `await`.
+
+```python
+from signalcore import Signalcore
+
+with Signalcore() as client:
+    for agent in client.agents.list().items:
+        print(agent.name)
+```
+
+## What you get
+
+- **Every endpoint of the API**, one attribute per family: `client.agents`, `client.runs`,
+  `client.conversations`, `client.requests`, `client.documents`, `client.records`,
+  `client.vault`, `client.connections`, `client.channels`, `client.skills` and the rest. Each
+  method names the operation it calls.
+- **Typed answers.** Responses are [pydantic](https://docs.pydantic.dev) models generated from
+  the API's contract (`signalcore.types`), so your editor and type checker know every field.
+- **Errors you can catch.** Failures raise `NotFoundError`, `ForbiddenError`, `InvalidError`
+  and the like (all `SignalcoreError`), carrying the API's `status`, `code`, `detail` and, for
+  a body that did not fit, the `errors` field by field.
+- **Lists that page.** Every list answers `items` and `next_cursor`. To read a whole list:
+  `client.iterate(client.conversations.list, status="open")`.
+- **Streams.** `client.runs.stream(run_id)` yields Server-Sent Events until the run is `done`
+  or `paused`; pass `last_event_id` to resume after a drop. `client.build.sessions.say(...)`
+  streams a builder turn.
+- **Several businesses.** An agency's key acts as each of its clients:
+  `client.for_org("org_...").agents.list()`.
+- **Live streams.** What a run shows as it happens is watched from a browser, over a WebSocket.
+  `client.live.url(stream_id)` is its address (`wss://<api>/v1/live/<id>?token=...`, with this
+  client's credential in the query): give it to `@signalcore/ui`'s `LiveView` or the TypeScript
+  client's `live.connect`, only when the client holds an end user's token or a publishable key. It
+  carries the credential, so never hand a browser one made with a secret key.
+
+## End users in the browser
+
+The people who use your product can talk to your agents without your secret key ever reaching
+their browser. Your backend asks for a token for a person it knows and hands it over:
+
+```python
+minted = await client.end_users.mint_token("user-42", name="Ana", email="ana@example.com")
+# Hand minted.token to their browser: new Signalcore({ endUserToken }) in @signalcore/sdk,
+# or AsyncSignalcore(end_user_token=...) from Python.
+```
+
+For visitors who are not signed in, make a publishable key that works only from your pages
+(`client.publishable_keys.create("Shop", ["https://shop.example.com"])`) and give the client
+`publishable_key=` with a `visitor_id=` the browser keeps. Both credentials can talk to live
+agents and read their own runs, and nothing else; `caller` is who the credential says.
+
+## Your own components
+
+What an agent can draw (cards, tables, forms) is a closed catalog, but your product has cards of
+its own. Register one by name, with the props it takes and a text for doors that cannot draw it,
+and agents can show it; your app draws it:
+
+```python
+await client.ui.components.put(
+    "PropertyCard",
+    "Property card",
+    "A listing the customer asked about",  # what the agent should use it for
+    {
+        "type": "object",
+        "properties": {"address": {"type": "string"}, "price": {"type": "number"}},
+        "required": ["address", "price"],
+    },
+    "{address}\nPrice: {price} EUR",  # the text twin; {prop} is filled from the props
+)
+```
+
+The schema is a small subset of JSON Schema: strings, numbers, whole numbers, booleans, lists of
+those and one level of object; anything else is refused. An agent shows the component as a
+`Host` node, `{"id": "home", "component": "Host", "name": "PropertyCard", "props": {...}}`
+(`sc.ui.host("PropertyCard", {...})` in agent code). Its props are checked against your schema
+before anyone sees them, and the text twin is the surface's text when the agent wrote none.
+`client.ui.catalog()` lists your components after the built-in ones.
+
+## Configuration
+
+```python
+AsyncSignalcore(
+    api_key=None,  # else SIGNALCORE_API_KEY
+    end_user_token=None,  # instead of api_key: a person of your product, in their browser
+    publishable_key=None,  # instead of api_key: a visitor, with visitor_id (8-128 characters)
+    visitor_id=None,
+    base_url=None,  # else SIGNALCORE_BASE_URL, else https://signalcore.ai
+    org=None,  # act as a business this key manages
+    timeout=30,  # seconds
+)
+```
+
+Pass exactly one of `api_key`, `end_user_token` and `publishable_key`.
+
+Keys carry scopes (`agents:read`, `runs:write`...), so a key made for one job can do only
+that job; a call outside its scopes raises `ForbiddenError`.
+
+## Documentation
+
+Guides and the full API reference: <https://signalcore.ai/docs>.
+
+MIT licensed.

signalcore-0.1.0/README.md

@@ -0,0 +1,142 @@
+# signalcore
+
+The Python client for [SignalCore](https://signalcore.ai): create agents, talk to them, and run
+everything around them (conversations, approvals, knowledge, records, apps) from your own code.
+
+```bash
+pip install signalcore
+```
+
+Python 3.11 or newer. Create an API key in the web app and export it:
+
+```bash
+export SIGNALCORE_API_KEY=sk_live_...
+```
+
+## Quickstart
+
+```python
+import asyncio
+
+from signalcore import AsyncSignalcore
+
+
+async def main() -> None:
+    async with AsyncSignalcore() as client:  # reads SIGNALCORE_API_KEY
+        agent = await client.agents.create("Reception", instructions="You answer for Clínica Sol.")
+        await client.agents.publish(agent.id)
+
+        answer = await client.agents.invoke(
+            agent.id, input="Do you open on Saturdays?", thread="ticket-7"
+        )
+        print(answer.text)
+
+        async for event in client.runs.stream(answer.run_id):  # the run's journal, live
+            print(event.event, event.json())
+
+
+asyncio.run(main())
+```
+
+Code that does not use `asyncio` imports `Signalcore` instead: the same client, same names,
+no `await`.
+
+```python
+from signalcore import Signalcore
+
+with Signalcore() as client:
+    for agent in client.agents.list().items:
+        print(agent.name)
+```
+
+## What you get
+
+- **Every endpoint of the API**, one attribute per family: `client.agents`, `client.runs`,
+  `client.conversations`, `client.requests`, `client.documents`, `client.records`,
+  `client.vault`, `client.connections`, `client.channels`, `client.skills` and the rest. Each
+  method names the operation it calls.
+- **Typed answers.** Responses are [pydantic](https://docs.pydantic.dev) models generated from
+  the API's contract (`signalcore.types`), so your editor and type checker know every field.
+- **Errors you can catch.** Failures raise `NotFoundError`, `ForbiddenError`, `InvalidError`
+  and the like (all `SignalcoreError`), carrying the API's `status`, `code`, `detail` and, for
+  a body that did not fit, the `errors` field by field.
+- **Lists that page.** Every list answers `items` and `next_cursor`. To read a whole list:
+  `client.iterate(client.conversations.list, status="open")`.
+- **Streams.** `client.runs.stream(run_id)` yields Server-Sent Events until the run is `done`
+  or `paused`; pass `last_event_id` to resume after a drop. `client.build.sessions.say(...)`
+  streams a builder turn.
+- **Several businesses.** An agency's key acts as each of its clients:
+  `client.for_org("org_...").agents.list()`.
+- **Live streams.** What a run shows as it happens is watched from a browser, over a WebSocket.
+  `client.live.url(stream_id)` is its address (`wss://<api>/v1/live/<id>?token=...`, with this
+  client's credential in the query): give it to `@signalcore/ui`'s `LiveView` or the TypeScript
+  client's `live.connect`, only when the client holds an end user's token or a publishable key. It
+  carries the credential, so never hand a browser one made with a secret key.
+
+## End users in the browser
+
+The people who use your product can talk to your agents without your secret key ever reaching
+their browser. Your backend asks for a token for a person it knows and hands it over:
+
+```python
+minted = await client.end_users.mint_token("user-42", name="Ana", email="ana@example.com")
+# Hand minted.token to their browser: new Signalcore({ endUserToken }) in @signalcore/sdk,
+# or AsyncSignalcore(end_user_token=...) from Python.
+```
+
+For visitors who are not signed in, make a publishable key that works only from your pages
+(`client.publishable_keys.create("Shop", ["https://shop.example.com"])`) and give the client
+`publishable_key=` with a `visitor_id=` the browser keeps. Both credentials can talk to live
+agents and read their own runs, and nothing else; `caller` is who the credential says.
+
+## Your own components
+
+What an agent can draw (cards, tables, forms) is a closed catalog, but your product has cards of
+its own. Register one by name, with the props it takes and a text for doors that cannot draw it,
+and agents can show it; your app draws it:
+
+```python
+await client.ui.components.put(
+    "PropertyCard",
+    "Property card",
+    "A listing the customer asked about",  # what the agent should use it for
+    {
+        "type": "object",
+        "properties": {"address": {"type": "string"}, "price": {"type": "number"}},
+        "required": ["address", "price"],
+    },
+    "{address}\nPrice: {price} EUR",  # the text twin; {prop} is filled from the props
+)
+```
+
+The schema is a small subset of JSON Schema: strings, numbers, whole numbers, booleans, lists of
+those and one level of object; anything else is refused. An agent shows the component as a
+`Host` node, `{"id": "home", "component": "Host", "name": "PropertyCard", "props": {...}}`
+(`sc.ui.host("PropertyCard", {...})` in agent code). Its props are checked against your schema
+before anyone sees them, and the text twin is the surface's text when the agent wrote none.
+`client.ui.catalog()` lists your components after the built-in ones.
+
+## Configuration
+
+```python
+AsyncSignalcore(
+    api_key=None,  # else SIGNALCORE_API_KEY
+    end_user_token=None,  # instead of api_key: a person of your product, in their browser
+    publishable_key=None,  # instead of api_key: a visitor, with visitor_id (8-128 characters)
+    visitor_id=None,
+    base_url=None,  # else SIGNALCORE_BASE_URL, else https://signalcore.ai
+    org=None,  # act as a business this key manages
+    timeout=30,  # seconds
+)
+```
+
+Pass exactly one of `api_key`, `end_user_token` and `publishable_key`.
+
+Keys carry scopes (`agents:read`, `runs:write`...), so a key made for one job can do only
+that job; a call outside its scopes raises `ForbiddenError`.
+
+## Documentation
+
+Guides and the full API reference: <https://signalcore.ai/docs>.
+
+MIT licensed.

signalcore-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "signalcore"
+version = "0.1.0"
+description = "The Python client for SignalCore: create agents, talk to them and run everything around them."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = ["signalcore", "agents", "ai", "sdk", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "anyio>=4.5",
+    "httpx>=0.28",
+    "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://signalcore.ai"
+Documentation = "https://signalcore.ai/docs"
+Repository = "https://github.com/OmnistGroup/signalcore/tree/staging/clients/python"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/signalcore"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/signalcore", "README.md", "LICENSE"]
+
+# Ruff reads the nearest config: this one keeps the repo's rules and lowers the target to the
+# oldest Python the package supports (the rest of the repo runs on 3.12).
+[tool.ruff]
+extend = "../../pyproject.toml"
+target-version = "py311"

signalcore-0.1.0/src/signalcore/__init__.py

@@ -0,0 +1,40 @@
+"""The Python client for SignalCore.
+
+    from signalcore import AsyncSignalcore, Signalcore
+
+``AsyncSignalcore`` is the client; ``Signalcore`` is the same one for code that blocks.
+Responses are the models in ``signalcore.types``, generated from the API's contract.
+"""
+
+from signalcore._client import AsyncSignalcore
+from signalcore._sse import ServerSentEvent
+from signalcore._sync import Signalcore
+from signalcore._version import __version__
+from signalcore.errors import (
+    ConflictError,
+    ForbiddenError,
+    InvalidError,
+    NotFoundError,
+    RateLimitedError,
+    ServerError,
+    SignalcoreError,
+    UnauthenticatedError,
+)
+from signalcore.events import RunEvent, UnknownEvent
+
+__all__ = [
+    "AsyncSignalcore",
+    "ConflictError",
+    "ForbiddenError",
+    "InvalidError",
+    "NotFoundError",
+    "RateLimitedError",
+    "RunEvent",
+    "ServerError",
+    "ServerSentEvent",
+    "Signalcore",
+    "SignalcoreError",
+    "UnauthenticatedError",
+    "UnknownEvent",
+    "__version__",
+]

signalcore-0.1.0/src/signalcore/_client.py

@@ -0,0 +1,177 @@
+"""The async client: credentials and a connection, with the API's families mounted on it."""
+
+import os
+from collections.abc import AsyncIterator, Awaitable, Callable
+from types import TracebackType
+from typing import Any, Self
+
+import httpx
+
+from signalcore._http import ORG_HEADER, VISITOR_HEADER, Http
+from signalcore._pages import Item, Page, pages
+from signalcore._version import __version__
+from signalcore.resources.agents import Agents
+from signalcore.resources.api_keys import ApiKeys
+from signalcore.resources.billing import Billing
+from signalcore.resources.browser import Browser
+from signalcore.resources.build import Build
+from signalcore.resources.channels import Channels
+from signalcore.resources.connections import Connections
+from signalcore.resources.contacts import Contacts
+from signalcore.resources.conversations import Conversations
+from signalcore.resources.documents import Documents
+from signalcore.resources.end_users import EndUsers
+from signalcore.resources.files import Files
+from signalcore.resources.live import Live
+from signalcore.resources.memories import Memories
+from signalcore.resources.org import Org
+from signalcore.resources.orgs import Orgs
+from signalcore.resources.playground import Playground
+from signalcore.resources.publishable_keys import PublishableKeys
+from signalcore.resources.records import Records
+from signalcore.resources.requests import Requests
+from signalcore.resources.runs import Runs
+from signalcore.resources.skills import Skills
+from signalcore.resources.ui import Ui
+from signalcore.resources.usage import Usage
+from signalcore.resources.vault import Vault
+
+DEFAULT_BASE_URL = "https://signalcore.ai"
+API_KEY_VARIABLE = "SIGNALCORE_API_KEY"
+BASE_URL_VARIABLE = "SIGNALCORE_BASE_URL"
+
+
+def _credential(
+    api_key: str | None,
+    end_user_token: str | None,
+    publishable_key: str | None,
+    visitor_id: str | None,
+) -> dict[str, str]:
+    """The headers that say who is calling: exactly one of a secret key, an end user's token,
+    or a publishable key together with the visitor's id."""
+    passed = {
+        name: value
+        for name, value in (
+            ("api_key", api_key),
+            ("end_user_token", end_user_token),
+            ("publishable_key", publishable_key),
+        )
+        if value
+    }
+    if len(passed) > 1:
+        raise ValueError(
+            f"Pass one of api_key, end_user_token or publishable_key, not {', '.join(passed)}"
+        )
+    if visitor_id and not publishable_key:
+        raise ValueError("visitor_id goes with publishable_key")
+    if publishable_key:
+        if not visitor_id:
+            raise ValueError("A publishable_key needs the visitor_id the browser keeps")
+        return {"Authorization": f"Bearer {publishable_key}", VISITOR_HEADER: visitor_id}
+    if end_user_token:
+        return {"Authorization": f"Bearer {end_user_token}"}
+    key = api_key or os.environ.get(API_KEY_VARIABLE)
+    if not key:
+        raise ValueError(
+            f"Pass api_key, end_user_token or publishable_key, or set {API_KEY_VARIABLE}"
+        )
+    return {"Authorization": f"Bearer {key}"}
+
+
+class AsyncSignalcore:
+    """A client for the SignalCore API.
+
+    It acts with one credential. Your servers use a secret key, from ``api_key`` or
+    ``SIGNALCORE_API_KEY``. Where a browser holds the client, pass ``end_user_token`` (minted
+    for a person of your product by ``end_users.mint_token``) or ``publishable_key`` with the
+    ``visitor_id`` the browser keeps; those can talk to agents and read their own runs, nothing
+    more. The address comes from ``base_url`` or ``SIGNALCORE_BASE_URL``. ``org`` makes every
+    call act as a business the key manages (``for_org`` does it for a few). ``transport``
+    replaces the network, to run against an app in-process in tests.
+
+        async with AsyncSignalcore() as client:
+            agent = await client.agents.create("Reception")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        end_user_token: str | None = None,
+        publishable_key: str | None = None,
+        visitor_id: str | None = None,
+        base_url: str | None = None,
+        org: str | None = None,
+        timeout: float = 30,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        address = base_url or os.environ.get(BASE_URL_VARIABLE) or DEFAULT_BASE_URL
+        headers = {
+            **_credential(api_key, end_user_token, publishable_key, visitor_id),
+            "Accept": "application/json",
+            "User-Agent": f"signalcore-python/{__version__}",
+            **({ORG_HEADER: org} if org else {}),
+        }
+        self._mount(
+            Http(
+                httpx.AsyncClient(base_url=address, timeout=timeout, transport=transport),
+                headers,
+                timeout=timeout,
+                owns_client=True,
+            )
+        )
+
+    def _mount(self, http: Http) -> None:
+        self._http = http
+        self.orgs = Orgs(http)
+        self.api_keys = ApiKeys(http)
+        self.org = Org(http)
+        self.agents = Agents(http)
+        self.build = Build(http)
+        self.runs = Runs(http)
+        self.playground = Playground(http)
+        self.conversations = Conversations(http)
+        self.contacts = Contacts(http)
+        self.requests = Requests(http)
+        self.documents = Documents(http)
+        self.end_users = EndUsers(http)
+        self.publishable_keys = PublishableKeys(http)
+        self.memories = Memories(http)
+        self.records = Records(http)
+        self.files = Files(http)
+        self.vault = Vault(http)
+        self.connections = Connections(http)
+        self.channels = Channels(http)
+        self.skills = Skills(http)
+        self.usage = Usage(http)
+        self.billing = Billing(http)
+        self.ui = Ui(http)
+        self.browser = Browser(http)
+        self.live = Live(http)
+
+    def for_org(self, org_id: str) -> Self:
+        """A client acting as a business this one manages (``orgs.create``), sharing its
+        connection. Closing it leaves the connection to the client it came from."""
+        client = object.__new__(type(self))
+        client._mount(self._http.acting_as(org_id))
+        return client
+
+    @staticmethod
+    def iterate(fetch: Callable[..., Awaitable[Page[Item]]], **params: Any) -> AsyncIterator[Item]:
+        """Every item of a paged list, page after page:
+        ``client.iterate(client.conversations.list, status="open")``."""
+        return pages(fetch, **params)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()