syntri-contracts 0.3.1__tar.gz

syntri_contracts-0.3.1/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Domani Labs. All rights reserved.
+
+This software and associated documentation files (the "Software") are
+proprietary and confidential. Unauthorized copying, distribution,
+modification, or use of this Software, in whole or in part, without
+prior written permission from Domani Labs is strictly prohibited.
+
+For licensing enquiries: info@domanimedia.com

syntri_contracts-0.3.1/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: syntri-contracts
+Version: 0.3.1
+Summary: Public contracts and building blocks for Syntri capability packs
+Author: Domani Labs
+License: Proprietary
+Project-URL: Homepage, https://github.com/DomaniLabs/Syntri
+Project-URL: Documentation, https://github.com/DomaniLabs/Syntri/contracts
+Keywords: agent,orchestration,capability,nlp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.9
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pyyaml>=6; extra == "dev"
+Requires-Dist: ruff>=0.7; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <strong>Agent infrastructure for production AI.</strong><br/>
+  Build, train, deploy and continuously improve domain-specific AI agents.
+</p>
+
+<p align="center">
+  <a href="https://syntri.ai">syntri.ai</a> &nbsp;·&nbsp;
+  <a href="mailto:hello@domani.studio">Request access</a> &nbsp;·&nbsp;
+  Built by <a href="https://domani.studio">Domani</a>
+</p>
+
+---
+
+## What it is
+
+Most AI integrations are wrappers around a language model. You call an API, get a completion, and hope it does the right thing. When it doesn't, you have no visibility into why — and no way to make it better without starting over.
+
+Syntri is different. It is infrastructure for building AI agents that are **measurable, improvable, and production-safe** — agents that get better the longer they run, without requiring you to trust a black box.
+
+## Two modules, one platform
+
+**Syntri Agent** — Build and operate domain-specific AI agents. Define what your agent understands, train models on your own data, connect your systems through capability packs, and enforce policies that keep sensitive operations safe. Language models are optional; custom-trained models are first-class.
+
+**Syntri Observe** — AI-native observability. Not just logs — decision logs. See intent accuracy over time, entity extraction failure rates by field, outcome-weighted performance across capabilities, and where your agent is degrading before your users tell you.
+
+## How it works
+
+Your data → Train your models → Deploy your agent → Collect experience → Improve
+
+
+Every agent instance trains on its own data. Syntri provides the infrastructure — the training pipeline, the evaluation harness, the runtime, the observability layer. You bring the domain knowledge.
+
+```yaml
+# An agent instance is configuration, not code
+agent:
+  name: your-agent
+  locales: [en, sw, pcm]
+
+capabilities:
+  - payments
+  - flights
+  - customer-support
+
+learning:
+  level: 3          # classical ML — intent + entity models
+  retrain_every_days: 14
+```
+
+## What makes it different
+
+**Decision-level observability.** Existing tools tell you an API call succeeded. Syntri tells you the agent routed to `send_money` at 0.61 confidence, the bank extractor has an 18% error rate on three-word institution names, and session abandonment on the flight booking capability jumped 12 points this week.
+
+**Custom-trained models.** The failure modes that matter most — local bank aliases, pidgin shorthand, currency formats, SMS abbreviations — are coverage problems. They are fixed by training on your distribution, not by engineering prompts. Syntri makes that trainable.
+
+**Learns from experience.** Every production turn is a training candidate. Corrections, completions, abandonments — all become supervision signal. The agent improves on a gated, offline cadence. Nothing updates live.
+
+**LLM-optional.** Language models are one component in the stack, not the foundation. An agent running at learning level 3 uses a trained intent classifier (~10ms, no API cost) and falls back to an LLM only for low-confidence or unmapped cases. At level 4 and above, a fine-tuned transformer handles everything.
+
+**Safe by design.** Money-moving operations are typed as `irreversible` in the taxonomy. The runtime refuses to execute them locally — they are requests to your backend, not commands. No configuration or capability pack can override this.
+
+## Status
+
+Private beta. Infinitswap is our first production deployment — a WhatsApp-native financial platform operating across Nigeria, Ghana, Tanzania and South Africa.
+
+[Request access →](mailto:hello@domani.studio)
+
+---
+
+## Connecting to Syntri
+
+Syntri runs as a standalone service. Your application calls it over HTTP — no Python required on your side.
+
+```bash
+# Understand a message
+POST /v1/understand
+{ "text": "send 5k to my uba account", "session_id": "...", "user_id": "..." }
+
+# Full agent turn
+POST /v1/turn
+{ "text": "...", "session_id": "...", "channel": "whatsapp" }
+
+# Return tool results
+POST /v1/tool-results
+{ "session_id": "...", "results": [...] }
+
+# Send outcome feedback (closes the learning loop)
+POST /v1/feedback
+{ "session_id": "...", "outcome": "completed" }
+```
+
+An SDK and CLI are in development. See [`/contracts`](/contracts) for the full API schema.
+
+## Building capability packs
+
+A **capability pack** is a small Python package that teaches an agent how to
+handle one job — checking a balance, booking a flight, opening a ticket. Packs
+declare tools and decision logic; the customer's backend does the execution.
+Money-moving operations can never run in the agent — the contract enforces it.
+
+```bash
+pip install syntri-contracts
+```
+
+```python
+from syntri_contracts.contracts.capability import (
+    CapabilityManifest, CapabilityPack, Decision, WorkflowStatus,
+)
+
+class CheckBalancePack(CapabilityPack):
+    manifest = CapabilityManifest(
+        name="my-check-balance", display_name="Check Balance",
+        version="0.1.0", description="Reports the user's balance.",
+        author="you@example.com", intents=["check_balance"],
+        required_entities=[], entry_point="my_pack.pack:CheckBalancePack",
+    )
+
+    def tools(self):
+        ...  # declare a ToolSpec, e.g. "balance.fetch" (executor=BACKEND)
+
+    def advance(self, session_id, slots, understanding, tool_results, turn_count):
+        if not tool_results:
+            return Decision(action="request_tool", tool="balance.fetch",
+                            arguments={}, status=WorkflowStatus.EXECUTING)
+        data = tool_results[-1].data or {}
+        return Decision(action="reply",
+                        message=f"Your balance is {data.get('balance')}.",
+                        status=WorkflowStatus.COMPLETED)
+```
+
+Full guide: [`contracts/README.md`](/contracts/README.md). Working template:
+[`contracts/example_pack/`](/contracts/example_pack). Validate a pack with
+`syntri pack validate ./my-pack/`.
+
+## Deployment
+
+Self-hosted first. Syntri runs inside your infrastructure — your data never leaves your environment.
+
+Your infrastructure
+├── Your application (Node, Python, anything)
+├── Syntri Agent ← runs here, calls back to your app for tool execution
+└── Your database
+
+
+Docker image and Helm chart coming with the beta release.
+
+---
+
+## Roadmap
+
+- [x] Experience schema — Observation, Interpretation, Judgment, Episode
+- [x] Config-driven taxonomy with risk tiers and slot rules
+- [x] PII tokenisation at ingestion
+- [x] Plugin discovery — connectors, capabilities, noise packs
+- [x] Model registry with lineage and promotion gates
+- [ ] Corpus builder and synthetic augmentation
+- [ ] Intent classifier + entity extractor training pipeline
+- [ ] Infinitswap connector (first production adapter)
+- [ ] Shadow mode deployment on Infinitswap traffic
+- [ ] Flight booking capability pack
+- [x] Public capability-pack contract (`syntri-contracts`) — *Phase 5, in progress*
+- [ ] `syntri pack validate` and marketplace submission
+- [ ] CLI: `syntri init`, `syntri train`, `syntri evaluate`, `syntri serve`
+- [ ] Syntri Observe dashboard
+
+---
+
+<p align="center">
+  <sub>Built by <a href="https://domani.studio">Domani</a> · © 2026 Domani Labs · All rights reserved</sub>
+</p>

syntri_contracts-0.3.1/README.md

@@ -0,0 +1,169 @@
+<p align="center">
+  <strong>Agent infrastructure for production AI.</strong><br/>
+  Build, train, deploy and continuously improve domain-specific AI agents.
+</p>
+
+<p align="center">
+  <a href="https://syntri.ai">syntri.ai</a> &nbsp;·&nbsp;
+  <a href="mailto:hello@domani.studio">Request access</a> &nbsp;·&nbsp;
+  Built by <a href="https://domani.studio">Domani</a>
+</p>
+
+---
+
+## What it is
+
+Most AI integrations are wrappers around a language model. You call an API, get a completion, and hope it does the right thing. When it doesn't, you have no visibility into why — and no way to make it better without starting over.
+
+Syntri is different. It is infrastructure for building AI agents that are **measurable, improvable, and production-safe** — agents that get better the longer they run, without requiring you to trust a black box.
+
+## Two modules, one platform
+
+**Syntri Agent** — Build and operate domain-specific AI agents. Define what your agent understands, train models on your own data, connect your systems through capability packs, and enforce policies that keep sensitive operations safe. Language models are optional; custom-trained models are first-class.
+
+**Syntri Observe** — AI-native observability. Not just logs — decision logs. See intent accuracy over time, entity extraction failure rates by field, outcome-weighted performance across capabilities, and where your agent is degrading before your users tell you.
+
+## How it works
+
+Your data → Train your models → Deploy your agent → Collect experience → Improve
+
+
+Every agent instance trains on its own data. Syntri provides the infrastructure — the training pipeline, the evaluation harness, the runtime, the observability layer. You bring the domain knowledge.
+
+```yaml
+# An agent instance is configuration, not code
+agent:
+  name: your-agent
+  locales: [en, sw, pcm]
+
+capabilities:
+  - payments
+  - flights
+  - customer-support
+
+learning:
+  level: 3          # classical ML — intent + entity models
+  retrain_every_days: 14
+```
+
+## What makes it different
+
+**Decision-level observability.** Existing tools tell you an API call succeeded. Syntri tells you the agent routed to `send_money` at 0.61 confidence, the bank extractor has an 18% error rate on three-word institution names, and session abandonment on the flight booking capability jumped 12 points this week.
+
+**Custom-trained models.** The failure modes that matter most — local bank aliases, pidgin shorthand, currency formats, SMS abbreviations — are coverage problems. They are fixed by training on your distribution, not by engineering prompts. Syntri makes that trainable.
+
+**Learns from experience.** Every production turn is a training candidate. Corrections, completions, abandonments — all become supervision signal. The agent improves on a gated, offline cadence. Nothing updates live.
+
+**LLM-optional.** Language models are one component in the stack, not the foundation. An agent running at learning level 3 uses a trained intent classifier (~10ms, no API cost) and falls back to an LLM only for low-confidence or unmapped cases. At level 4 and above, a fine-tuned transformer handles everything.
+
+**Safe by design.** Money-moving operations are typed as `irreversible` in the taxonomy. The runtime refuses to execute them locally — they are requests to your backend, not commands. No configuration or capability pack can override this.
+
+## Status
+
+Private beta. Infinitswap is our first production deployment — a WhatsApp-native financial platform operating across Nigeria, Ghana, Tanzania and South Africa.
+
+[Request access →](mailto:hello@domani.studio)
+
+---
+
+## Connecting to Syntri
+
+Syntri runs as a standalone service. Your application calls it over HTTP — no Python required on your side.
+
+```bash
+# Understand a message
+POST /v1/understand
+{ "text": "send 5k to my uba account", "session_id": "...", "user_id": "..." }
+
+# Full agent turn
+POST /v1/turn
+{ "text": "...", "session_id": "...", "channel": "whatsapp" }
+
+# Return tool results
+POST /v1/tool-results
+{ "session_id": "...", "results": [...] }
+
+# Send outcome feedback (closes the learning loop)
+POST /v1/feedback
+{ "session_id": "...", "outcome": "completed" }
+```
+
+An SDK and CLI are in development. See [`/contracts`](/contracts) for the full API schema.
+
+## Building capability packs
+
+A **capability pack** is a small Python package that teaches an agent how to
+handle one job — checking a balance, booking a flight, opening a ticket. Packs
+declare tools and decision logic; the customer's backend does the execution.
+Money-moving operations can never run in the agent — the contract enforces it.
+
+```bash
+pip install syntri-contracts
+```
+
+```python
+from syntri_contracts.contracts.capability import (
+    CapabilityManifest, CapabilityPack, Decision, WorkflowStatus,
+)
+
+class CheckBalancePack(CapabilityPack):
+    manifest = CapabilityManifest(
+        name="my-check-balance", display_name="Check Balance",
+        version="0.1.0", description="Reports the user's balance.",
+        author="you@example.com", intents=["check_balance"],
+        required_entities=[], entry_point="my_pack.pack:CheckBalancePack",
+    )
+
+    def tools(self):
+        ...  # declare a ToolSpec, e.g. "balance.fetch" (executor=BACKEND)
+
+    def advance(self, session_id, slots, understanding, tool_results, turn_count):
+        if not tool_results:
+            return Decision(action="request_tool", tool="balance.fetch",
+                            arguments={}, status=WorkflowStatus.EXECUTING)
+        data = tool_results[-1].data or {}
+        return Decision(action="reply",
+                        message=f"Your balance is {data.get('balance')}.",
+                        status=WorkflowStatus.COMPLETED)
+```
+
+Full guide: [`contracts/README.md`](/contracts/README.md). Working template:
+[`contracts/example_pack/`](/contracts/example_pack). Validate a pack with
+`syntri pack validate ./my-pack/`.
+
+## Deployment
+
+Self-hosted first. Syntri runs inside your infrastructure — your data never leaves your environment.
+
+Your infrastructure
+├── Your application (Node, Python, anything)
+├── Syntri Agent ← runs here, calls back to your app for tool execution
+└── Your database
+
+
+Docker image and Helm chart coming with the beta release.
+
+---
+
+## Roadmap
+
+- [x] Experience schema — Observation, Interpretation, Judgment, Episode
+- [x] Config-driven taxonomy with risk tiers and slot rules
+- [x] PII tokenisation at ingestion
+- [x] Plugin discovery — connectors, capabilities, noise packs
+- [x] Model registry with lineage and promotion gates
+- [ ] Corpus builder and synthetic augmentation
+- [ ] Intent classifier + entity extractor training pipeline
+- [ ] Infinitswap connector (first production adapter)
+- [ ] Shadow mode deployment on Infinitswap traffic
+- [ ] Flight booking capability pack
+- [x] Public capability-pack contract (`syntri-contracts`) — *Phase 5, in progress*
+- [ ] `syntri pack validate` and marketplace submission
+- [ ] CLI: `syntri init`, `syntri train`, `syntri evaluate`, `syntri serve`
+- [ ] Syntri Observe dashboard
+
+---
+
+<p align="center">
+  <sub>Built by <a href="https://domani.studio">Domani</a> · © 2026 Domani Labs · All rights reserved</sub>
+</p>

syntri_contracts-0.3.1/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "syntri-contracts"
+version = "0.3.1"
+description = "Public contracts and building blocks for Syntri capability packs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Domani Labs" }]
+keywords = ["agent", "orchestration", "capability", "nlp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+# Read from the imports of the extracted modules, not guessed:
+#   pydantic — contracts, experience.schema, and everything typed on them
+#   click    — the CLI (cli.fmt, cli.commands.pack, cli.main)
+dependencies = [
+    "pydantic>=2.9",
+    "click>=8.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pyyaml>=6", "ruff>=0.7", "mypy>=1.13"]
+
+[project.urls]
+Homepage = "https://github.com/DomaniLabs/Syntri"
+Documentation = "https://github.com/DomaniLabs/Syntri/contracts"
+
+# NOT named `syntri`: that console script belongs to syntri-core, and a second
+# package claiming it would shadow the real CLI depending on install order.
+[project.scripts]
+syntri-pack = "syntri_contracts.cli.main:main"
+
+[tool.setuptools]
+packages = [
+    "syntri_contracts",
+    "syntri_contracts.contracts",
+    "syntri_contracts.contracts.example_pack",
+    "syntri_contracts.experience",
+    "syntri_contracts.store",
+    "syntri_contracts.policy",
+    "syntri_contracts.nlu",
+    "syntri_contracts.capabilities",
+    "syntri_contracts.cli",
+    "syntri_contracts.cli.commands",
+]
+
+[tool.setuptools.package-data]
+# PEP 561. The packages are annotated; without this marker every consumer's
+# type checker silently treats the whole contract as Any, which is the
+# opposite of what a published contract is for.
+"syntri_contracts.contracts" = ["py.typed", "example_pack/manifest.yaml", "example_pack/fixtures/*.json", "example_pack/README.md"]
+"syntri_contracts.experience" = ["py.typed"]
+"syntri_contracts.store" = ["py.typed"]
+"syntri_contracts.policy" = ["py.typed"]
+"syntri_contracts.nlu" = ["py.typed"]
+"syntri_contracts.capabilities" = ["py.typed"]
+"syntri_contracts.cli" = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+# Same rule set syntri-core selects, so the extracted modules lint identically
+# on both sides. E501 (long lines) is confined to prose docstrings.
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501", "UP017", "UP042"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true

syntri_contracts-0.3.1/setup.cfg

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

syntri_contracts-0.3.1/syntri_contracts/__init__.py

@@ -0,0 +1,10 @@
+"""Public contracts and building blocks for Syntri capability packs.
+
+Everything third-party developers need to build, validate and run a capability
+pack, with no dependency on private syntri-core: the pack contract, the
+experience schema, the Store interface and its JsonlStore backend, the policy
+engine, the base NLU pipeline, the pack registry/replay machinery, and the
+`syntri-pack` CLI.
+"""
+
+__version__ = "0.3.1"

syntri_contracts-0.3.1/syntri_contracts/capabilities/__init__.py

@@ -0,0 +1,32 @@
+"""Capability pack machinery: registration and fixture replay.
+
+Both modules are built on the public `contracts` package and nothing else.
+`CapabilityRegistry` runs the startup checks the platform would (duplicate
+intents, money-on-agent, empty manifests); `replay_pack` drives a pack's
+fixtures through `advance()` with no server, network or model. Together they
+are what `syntri pack validate` runs.
+"""
+
+from syntri_contracts.capabilities.registry import (
+    ENTRY_POINT_GROUP,
+    CapabilityRegistry,
+    default_registry,
+)
+from syntri_contracts.capabilities.replay import (
+    FixtureOutcome,
+    ReplayReport,
+    TurnOutcome,
+    replay_fixture,
+    replay_pack,
+)
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "CapabilityRegistry",
+    "FixtureOutcome",
+    "ReplayReport",
+    "TurnOutcome",
+    "default_registry",
+    "replay_fixture",
+    "replay_pack",
+]