ucomm 0.0.1__tar.gz

ucomm-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Peter Foldiak
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ucomm-0.0.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: ucomm
+Version: 0.0.1
+Summary: Universal communicator middleware for Ethereum Swarm (working title)
+Author: Peter Foldiak
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/petfold/ucomm
+Project-URL: Repository, https://github.com/petfold/ucomm
+Project-URL: Issues, https://github.com/petfold/ucomm/issues
+Keywords: swarm,ethereum,web3,bee,messaging,chat,notifications,attention,middleware
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: recordstore[bee]>=0.13.1
+Requires-Dist: swarm-bee<2,>=1.1
+Requires-Dist: imapclient<4,>=3.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: hypothesis>=6; extra == "test"
+Requires-Dist: mypy>=1.10; extra == "test"
+Requires-Dist: ruff>=0.5; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ucomm[test]; extra == "dev"
+Dynamic: license-file
+
+# ucomm — universal communicator middleware for Ethereum Swarm
+
+[![tests](https://github.com/petfold/ucomm/actions/workflows/tests.yml/badge.svg)](https://github.com/petfold/ucomm/actions/workflows/tests.yml)
+[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+[![status](https://img.shields.io/badge/status-M2%20in%20progress-yellow)](docs/ROADMAP.md)
+
+*Working title. Naming is an open question (see ROADMAP.md, issue N-1).*
+
+Every communication app — chat, email, calls, streams, forums, social feeds — moves
+information of some kind from one or more people to one or more people. The apps
+differ in a handful of parameters (topology, interactivity, persistence, privacy,
+invitation granularity), not in principle. Yet on Swarm, as elsewhere, each project
+rebuilds the same primitives from scratch and ships its own silo, its own inbox,
+and its own notification settings.
+
+**ucomm** is middleware that factors out the common core:
+
+- a **channel kernel**: a channel is a set of per-author append-only logs, a merge
+  rule, and a parameter vector fixed at genesis; every event is one signed envelope.
+- an **attention layer**: a first-class control plane for requesting human attention,
+  based on Attila Lendvai's priority taxonomy (importance × urgency, ceilings,
+  offsets, thresholds), made incentive-compatible with postage costs, attention
+  bonds, and local reputation.
+- a **universal inbox**: one local notification daemon per device arbitrates all
+  attention requests across all channels and apps; apps become views and policy
+  defaults, not silos.
+- a **discovery/recommendation layer**: WoT-weighted collaborative filtering plus
+  concept-based (OntoDAG) content filtering, feeding priors into the attention
+  engine.
+
+Guiding principle: **receiver sovereignty**. Everything a sender or channel declares
+(priority, offsets, importance) is advisory and signed; the receiver's local policy
+engine is the only authority over the receiver's attention.
+
+## Repository layout
+
+```
+docs/DESIGN.md          Architecture: two planes, channel kernel, profiles, transports
+docs/ATTENTION.md       Attention economy: priority algebra, policy engine, mechanisms
+docs/RECOMMENDATION.md  Discovery & collaborative filtering (needs merge from prior notes)
+docs/ROADMAP.md         Module decomposition, milestones, initial issues
+docs/USER_GUIDE.md      Tutorial: motivation, project overview, install, worked examples
+CLAUDE.md               Instructions and invariants for Claude Code sessions
+src/ucomm/              Python package (schema, policy engine, signing, chat profile)
+tests/                  pytest suite
+```
+
+## Status
+
+**M0 (schema + algebra) and M1 (known-contact channels over Swarm) are done**
+— see `docs/ROADMAP.md` for the full milestone/issue breakdown. Concretely:
+the envelope/genesis schema with canonical encoding and validation; the
+priority algebra and policy engine with golden decision tests; per-author
+logs with deterministic causal-DAG merge, backed by either an in-memory
+implementation or a real recordstore/Bee adapter; real secp256k1 envelope
+signing (via `swarm-bee`) and out-of-band contact exchange; and a two-party/
+group chat profile exercising all of the above end-to-end, confirmed against
+a live Bee node. New here? Start with `docs/USER_GUIDE.md`.
+
+**M2 (notification daemon + universal inbox) is in progress**: a private
+channel directory, a graded active/obsolete dashboard (a projection,
+recomputed on demand — never persisted), read-state aggregation across
+every channel, a push/hint-delivery interface, and the IMAP bridge's
+conversion layer (email → the same envelopes and dashboard, no live
+mailbox yet) are done. Left: an actual hint backend, IMAP's live fetch
+loop, and the Nostr bridge — see `docs/USER_GUIDE.md` sections 11–13 for
+the directory/dashboard/hints/bridge demos. GSOC-based rendezvous
+(unsolicited contact, group discovery) stays behind the `Rendezvous`
+interface, pending the GSOC/pub-sub work by Viktor Tóth and Viktor Trón.
+Broadcast-style 1:N live streaming is explicitly out of scope here —
+Solar Punk Ltd's own `swarm-hls-stream`/`Swarmcast` line already owns that
+(DESIGN.md §5).
+
+**On decentralization, read this before evaluating further:** everything
+above runs on Swarm feeds and needs no full node — a light client is
+enough. Real-time push notification and unsolicited-contact discovery (PSS
+and GSOC) are a different story: both require a full node, yours or a
+relay's, and that relay sees traffic metadata, which is a real
+centralization point still unresolved (not just a caveat) — see
+`docs/DESIGN.md` §5 and §11. Nothing here should be evaluated as "fully
+decentralized" without that qualification.
+
+## Related projects
+
+- **recordstore** (github.com/petfold/recordstore) — candidate persistence substrate
+  for author logs (versioned key → record over Swarm; POT track).
+- **swarmfs** (github.com/petfold/swarmfs) — fsspec backend, useful for payload blobs.
+- **OntoDAG / mdl-fca** — semantic concept DAG; content-based half of the
+  recommendation layer.
+- Attila Lendvai, *Computer aided human communication*
+  (codeberg.org/attila.lendvai/publications) — source of the attention taxonomy.

ucomm-0.0.1/README.md

@@ -0,0 +1,91 @@
+# ucomm — universal communicator middleware for Ethereum Swarm
+
+[![tests](https://github.com/petfold/ucomm/actions/workflows/tests.yml/badge.svg)](https://github.com/petfold/ucomm/actions/workflows/tests.yml)
+[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+[![status](https://img.shields.io/badge/status-M2%20in%20progress-yellow)](docs/ROADMAP.md)
+
+*Working title. Naming is an open question (see ROADMAP.md, issue N-1).*
+
+Every communication app — chat, email, calls, streams, forums, social feeds — moves
+information of some kind from one or more people to one or more people. The apps
+differ in a handful of parameters (topology, interactivity, persistence, privacy,
+invitation granularity), not in principle. Yet on Swarm, as elsewhere, each project
+rebuilds the same primitives from scratch and ships its own silo, its own inbox,
+and its own notification settings.
+
+**ucomm** is middleware that factors out the common core:
+
+- a **channel kernel**: a channel is a set of per-author append-only logs, a merge
+  rule, and a parameter vector fixed at genesis; every event is one signed envelope.
+- an **attention layer**: a first-class control plane for requesting human attention,
+  based on Attila Lendvai's priority taxonomy (importance × urgency, ceilings,
+  offsets, thresholds), made incentive-compatible with postage costs, attention
+  bonds, and local reputation.
+- a **universal inbox**: one local notification daemon per device arbitrates all
+  attention requests across all channels and apps; apps become views and policy
+  defaults, not silos.
+- a **discovery/recommendation layer**: WoT-weighted collaborative filtering plus
+  concept-based (OntoDAG) content filtering, feeding priors into the attention
+  engine.
+
+Guiding principle: **receiver sovereignty**. Everything a sender or channel declares
+(priority, offsets, importance) is advisory and signed; the receiver's local policy
+engine is the only authority over the receiver's attention.
+
+## Repository layout
+
+```
+docs/DESIGN.md          Architecture: two planes, channel kernel, profiles, transports
+docs/ATTENTION.md       Attention economy: priority algebra, policy engine, mechanisms
+docs/RECOMMENDATION.md  Discovery & collaborative filtering (needs merge from prior notes)
+docs/ROADMAP.md         Module decomposition, milestones, initial issues
+docs/USER_GUIDE.md      Tutorial: motivation, project overview, install, worked examples
+CLAUDE.md               Instructions and invariants for Claude Code sessions
+src/ucomm/              Python package (schema, policy engine, signing, chat profile)
+tests/                  pytest suite
+```
+
+## Status
+
+**M0 (schema + algebra) and M1 (known-contact channels over Swarm) are done**
+— see `docs/ROADMAP.md` for the full milestone/issue breakdown. Concretely:
+the envelope/genesis schema with canonical encoding and validation; the
+priority algebra and policy engine with golden decision tests; per-author
+logs with deterministic causal-DAG merge, backed by either an in-memory
+implementation or a real recordstore/Bee adapter; real secp256k1 envelope
+signing (via `swarm-bee`) and out-of-band contact exchange; and a two-party/
+group chat profile exercising all of the above end-to-end, confirmed against
+a live Bee node. New here? Start with `docs/USER_GUIDE.md`.
+
+**M2 (notification daemon + universal inbox) is in progress**: a private
+channel directory, a graded active/obsolete dashboard (a projection,
+recomputed on demand — never persisted), read-state aggregation across
+every channel, a push/hint-delivery interface, and the IMAP bridge's
+conversion layer (email → the same envelopes and dashboard, no live
+mailbox yet) are done. Left: an actual hint backend, IMAP's live fetch
+loop, and the Nostr bridge — see `docs/USER_GUIDE.md` sections 11–13 for
+the directory/dashboard/hints/bridge demos. GSOC-based rendezvous
+(unsolicited contact, group discovery) stays behind the `Rendezvous`
+interface, pending the GSOC/pub-sub work by Viktor Tóth and Viktor Trón.
+Broadcast-style 1:N live streaming is explicitly out of scope here —
+Solar Punk Ltd's own `swarm-hls-stream`/`Swarmcast` line already owns that
+(DESIGN.md §5).
+
+**On decentralization, read this before evaluating further:** everything
+above runs on Swarm feeds and needs no full node — a light client is
+enough. Real-time push notification and unsolicited-contact discovery (PSS
+and GSOC) are a different story: both require a full node, yours or a
+relay's, and that relay sees traffic metadata, which is a real
+centralization point still unresolved (not just a caveat) — see
+`docs/DESIGN.md` §5 and §11. Nothing here should be evaluated as "fully
+decentralized" without that qualification.
+
+## Related projects
+
+- **recordstore** (github.com/petfold/recordstore) — candidate persistence substrate
+  for author logs (versioned key → record over Swarm; POT track).
+- **swarmfs** (github.com/petfold/swarmfs) — fsspec backend, useful for payload blobs.
+- **OntoDAG / mdl-fca** — semantic concept DAG; content-based half of the
+  recommendation layer.
+- Attila Lendvai, *Computer aided human communication*
+  (codeberg.org/attila.lendvai/publications) — source of the attention taxonomy.

ucomm-0.0.1/pyproject.toml

@@ -0,0 +1,43 @@
+[project.urls]
+Homepage = "https://github.com/petfold/ucomm"
+Repository = "https://github.com/petfold/ucomm"
+Issues = "https://github.com/petfold/ucomm/issues"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ucomm"
+version = "0.0.1"
+description = "Universal communicator middleware for Ethereum Swarm (working title)"
+requires-python = ">=3.11"
+keywords = ["swarm", "ethereum", "web3", "bee", "messaging", "chat", "notifications", "attention", "middleware"]
+readme = "README.md"
+license = { text = "BSD-3-Clause" }
+authors = [{ name = "Peter Foldiak" }]
+dependencies = ["recordstore[bee]>=0.13.1", "swarm-bee>=1.1,<2", "imapclient>=3.1,<4"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "hypothesis>=6", "mypy>=1.10", "ruff>=0.5"]
+dev = ["ucomm[test]"] # back-compat alias; [test] is the stack-wide name
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+
+[[tool.mypy.overrides]]
+module = "recordstore.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "imapclient.*"
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 96

ucomm-0.0.1/setup.cfg

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

ucomm-0.0.1/src/ucomm/__init__.py

@@ -0,0 +1,56 @@
+"""ucomm: universal communicator middleware for Ethereum Swarm (working title)."""
+
+from .attention import Decision, Intensity, PolicyState, SenderContext, decide
+from .contact import ContactCard, make_contact_card, verify_contact_card
+from .daemon import (
+    ChannelDirectory,
+    Dashboard,
+    DashboardItem,
+    DirectoryEntry,
+    build_dashboard,
+    directory_read_state,
+)
+from .envelope import AttentionClaim, Envelope, EventKind, Genesis, GenesisError, TimeWindow
+from .hints import HintSink, HintSource, InMemoryHints
+from .log import AuthorLog, merge_causal, read_state
+from .rendezvous import InMemoryRendezvous, Rendezvous
+from .signing import InvalidSignature, address_of, sign_envelope, verify_envelope
+from .store import RecordStoreAuthorLog, envelope_to_record, record_to_envelope
+
+__all__ = [
+    "AttentionClaim",
+    "AuthorLog",
+    "ChannelDirectory",
+    "ContactCard",
+    "Dashboard",
+    "DashboardItem",
+    "Decision",
+    "DirectoryEntry",
+    "Envelope",
+    "EventKind",
+    "Genesis",
+    "GenesisError",
+    "HintSink",
+    "HintSource",
+    "InMemoryHints",
+    "InMemoryRendezvous",
+    "Intensity",
+    "InvalidSignature",
+    "PolicyState",
+    "RecordStoreAuthorLog",
+    "Rendezvous",
+    "SenderContext",
+    "TimeWindow",
+    "address_of",
+    "build_dashboard",
+    "decide",
+    "directory_read_state",
+    "envelope_to_record",
+    "make_contact_card",
+    "merge_causal",
+    "read_state",
+    "record_to_envelope",
+    "sign_envelope",
+    "verify_contact_card",
+    "verify_envelope",
+]

ucomm-0.0.1/src/ucomm/attention.py

@@ -0,0 +1,116 @@
+"""Attention layer: priority algebra and policy engine (ATTENTION.md).
+
+Pure and deterministic by design: decide(envelope, policy, now) -> Decision is a
+function of its arguments only. All mutable state (ceilings, offsets, thresholds,
+reputation ratchet) lives in PolicyState, owned by the daemon.
+
+Receiver sovereignty: this module consumes AttentionClaim data and never
+constructs envelopes. One-way dependency: attention -> envelope, never reverse.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+from .envelope import Envelope, EventKind, PubKey
+
+
+class Intensity(IntEnum):
+    """Graded notification output (ATTENTION.md section 3)."""
+
+    FILED = 0        # silently filed; dashboard history only
+    BADGE = 1        # badge / dashboard, no interruption
+    SOFT = 2         # ring once / vibrate only
+    FULL = 3         # full alert
+    BREAKTHROUGH = 4 # overrides DND
+
+
+# Residual thresholds for grading, in log-scale priority units.
+SOFT_BAND = 5          # |residual| <= SOFT_BAND counts as "near threshold"
+BREAKTHROUGH_MARGIN = 20
+
+
+@dataclass(frozen=True)
+class PolicyState:
+    """Receiver-local policy snapshot. Never published, never negotiated."""
+
+    threshold: int  # current global threshold; DND = high value
+    default_ceiling_known: int = 40
+    default_ceiling_stranger: int = 0
+    wot_ceiling_slope: int = 10  # ceiling = base - slope * wot_distance (ATTENTION 5)
+    contact_ceilings: Mapping[PubKey, int] = field(default_factory=dict)
+    channel_offsets: Mapping[str, int] = field(default_factory=dict)
+    endpoint_offset: int = 0  # e.g. raised while in an interactive session
+    bond_credit: int = 10  # credibility bonus when valid collateral attached
+
+
+@dataclass(frozen=True)
+class SenderContext:
+    """What the receiver knows about the sender (from identity/WoT + recsys)."""
+
+    known_contact: bool
+    wot_distance: int | None = None  # None = no path
+    recsys_prior: int = 0  # advisory prior from RECOMMENDATION.md section 6
+    collateral_valid: bool = False
+
+
+@dataclass(frozen=True)
+class Decision:
+    intensity: Intensity
+    effective_priority: int
+    residual: int
+    ceiling_applied: int
+
+
+def ceiling_for(sender: PubKey, ctx: SenderContext, policy: PolicyState) -> int:
+    """Per-sender priority ceiling (ATTENTION.md sections 2, 5)."""
+    if sender in policy.contact_ceilings:
+        return policy.contact_ceilings[sender]
+    if ctx.known_contact:
+        return policy.default_ceiling_known
+    if ctx.wot_distance is not None:
+        base = policy.default_ceiling_known
+        return max(
+            policy.default_ceiling_stranger,
+            base - policy.wot_ceiling_slope * ctx.wot_distance + ctx.recsys_prior,
+        )
+    return policy.default_ceiling_stranger + ctx.recsys_prior
+
+
+def decide(env: Envelope, ctx: SenderContext, policy: PolicyState, now: float) -> Decision:
+    """Map one control-plane envelope to a graded notification intensity.
+
+    Pure function: (envelope, sender context, policy state, clock) -> Decision.
+    """
+    if env.kind is not EventKind.INVITATION or env.attention is None:
+        return Decision(Intensity.FILED, 0, -(10**6), 0)
+
+    claim = env.attention
+    if not claim.relevance.active(now):
+        return Decision(Intensity.FILED, 0, -(10**6), 0)  # expired -> timeline
+
+    cap = ceiling_for(env.author, ctx, policy)
+    credibility = policy.bond_credit if ctx.collateral_valid else 0
+
+    effective = (
+        min(claim.claimed_priority, cap)
+        + policy.channel_offsets.get(env.channel, 0)
+        + policy.endpoint_offset
+        + credibility
+    )
+    residual = effective - policy.threshold
+
+    if residual > BREAKTHROUGH_MARGIN:
+        intensity = Intensity.BREAKTHROUGH
+    elif residual > SOFT_BAND:
+        intensity = Intensity.FULL
+    elif residual > 0:
+        intensity = Intensity.SOFT
+    elif residual > -SOFT_BAND:
+        intensity = Intensity.BADGE
+    else:
+        intensity = Intensity.FILED
+
+    return Decision(intensity, effective, residual, cap)

ucomm-0.0.1/src/ucomm/bee.py

@@ -0,0 +1,51 @@
+"""Real Swarm-backed author logs (M1).
+
+Thin adapter from `RecordStoreAuthorLog` (`ucomm.store`) to recordstore's Bee
+backends -- `BeeBytesStore` + `SwarmFeedPointer` -- instead of the in-memory
+ones used for M0 prototyping. This is the "drop-in swap, not a rewrite"
+ROADMAP.md promised: `RecordStoreAuthorLog` only ever needed a
+`recordstore.RecordStore`; it never knew or cared whether that store was
+backed by memory or a live Bee node.
+
+Feeds need an IMMUTABLE postage batch (see CLAUDE.md, "Swarm facts to
+respect"). This module never buys one -- pass an existing usable batch id
+(`GET /stamps` on the target node), bought e.g. with
+`POST /stamps/{amount}/{depth}?immutable=true` or swarmfs's `StampManager`.
+"""
+
+from __future__ import annotations
+
+from recordstore import BeeBytesStore, RecordStore, SwarmFeedPointer
+
+from .envelope import ChannelId, PubKey
+from .signing import address_of
+from .store import RecordStoreAuthorLog
+
+
+def feed_topic(channel: ChannelId, author: PubKey) -> str:
+    """Feed topic namespacing one author's per-channel log."""
+    return f"ucomm/log/{channel}/{author}"
+
+
+def open_author_feed_log(
+    api_url: str, channel: ChannelId, *, signer_hex: str, postage_batch_id: str,
+) -> tuple[RecordStore, RecordStoreAuthorLog]:
+    """Open `signer_hex`'s own log for `channel`, backed by a real Swarm feed.
+
+    `signer_hex` is the author's private key (hex); the feed owner (and
+    hence `Envelope.author`, via `ucomm.signing.address_of`) is derived from
+    it. Returns `(store, log)`: append through `log`, then call
+    `store.commit()` to actually publish -- appends are staged locally until
+    then, same as any other `RecordStore` (issue K-4's batching model, not a
+    new one for Bee).
+    """
+    from bee.swarm.keys import PrivateKey
+
+    author: PubKey = address_of(PrivateKey.from_hex(signer_hex))
+    pointer = SwarmFeedPointer(
+        api_url, feed_topic(channel, author),
+        signer=signer_hex, postage_batch_id=postage_batch_id,
+    )
+    bytes_store = BeeBytesStore(api_url, postage_batch_id=postage_batch_id)
+    store = RecordStore(bytes_store, pointer=pointer)
+    return store, RecordStoreAuthorLog(store, channel, author)

ucomm-0.0.1/src/ucomm/bridges/__init__.py

@@ -0,0 +1,8 @@
+"""Bridges: adapters converting external protocols into ucomm envelopes.
+
+DESIGN.md section 10: every bridge is an inbox adapter into the same
+envelope schema and policy engine ucomm uses natively -- the "attention
+firewall" is a unified inbox across everything, not just Swarm-native
+channels. Kept out of the top-level `ucomm` namespace, same reasoning as
+`ucomm.profiles`: a layer above the kernel, not part of it.
+"""