team-core 0.4.0__py3-none-any.whl

team/__init__.py

@@ -0,0 +1,17 @@
+"""team — orchestrate a cluster of containerized local LLMs.
+
+A `team` is a set of `Member`s (each backed by an Ollama model running in its
+own Docker container) that collaborate to accomplish a `goal` according to a
+chosen `workflow` (round-robin, manager-driven, review-loop, ...).
+
+Public entry points:
+
+* :func:`team.config.load_team` — parse a YAML team spec.
+* :class:`team.orchestrator.Orchestrator` — bring members up, run a workflow,
+  tear them down.
+* :mod:`team.cli` — the ``team`` command-line interface.
+"""
+
+from team._version import __version__
+
+__all__ = ["__version__"]

team/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

team/beliefs.py

@@ -0,0 +1,259 @@
+"""Shared team belief board — structured collective knowledge.
+
+The :class:`BeliefBoard` lets team members collaboratively build and maintain
+a structured record of what the team collectively knows, believes, and contests.
+Each belief is a versioned claim with:
+
+* an author and confidence score (0.0 – 1.0)
+* optional supporting evidence
+* a **voting record**: members can accept or contest each belief
+* a status driven by consensus: ``pending`` → ``accepted`` / ``contested``
+
+The board is stored as ``<workspace>/beliefs.json`` so it persists across
+sessions and can be inspected with ``team beliefs myteam.yaml``.
+
+Consensus rules
+---------------
+A belief transitions from ``pending`` to ``accepted`` when the fraction of
+members who voted *for* it is ≥ ``consensus_threshold`` (default 0.5).  Any
+member can contest a belief, which immediately moves it to ``contested`` —
+regardless of prior votes — forcing the team to re-evaluate.
+
+Members can accept a previously contested belief, which re-triggers the
+consensus check.  A rejected belief stays ``rejected`` permanently unless
+explicitly re-asserted with a new claim.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# --------------------------------------------------------------------------- #
+# Data model
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class Belief:
+    id: str
+    claim: str
+    author: str
+    confidence: float          # 0.0 – 1.0
+    evidence: str
+    status: str                # pending | accepted | contested | rejected
+    votes_for: list[str]       # member names who accepted
+    votes_against: list[str]   # member names who contested
+    reasons: dict[str, str]    # member → reason for contesting
+    created_at: float
+    updated_at: float
+
+
+# --------------------------------------------------------------------------- #
+# BeliefBoard
+# --------------------------------------------------------------------------- #
+
+
+class BeliefBoard:
+    """Shared, persistent belief store for a team."""
+
+    def __init__(
+        self,
+        path: Path,
+        member_names: list[str],
+        consensus_threshold: float = 0.5,
+    ) -> None:
+        self.path = Path(path)
+        self.member_names = list(member_names)
+        self.consensus_threshold = max(0.0, min(1.0, consensus_threshold))
+        self._beliefs: dict[str, Belief] = {}
+        self._load()
+
+    # ------------------------------------------------------------------ #
+    # Persistence
+    # ------------------------------------------------------------------ #
+
+    def _load(self) -> None:
+        if not self.path.exists():
+            return
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+            for item in raw:
+                b = Belief(**item)
+                self._beliefs[b.id] = b
+        except (json.JSONDecodeError, TypeError, KeyError):
+            # Corrupt file — start fresh rather than crashing.
+            self._beliefs = {}
+
+    def _save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        data = [asdict(b) for b in self._beliefs.values()]
+        self.path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    # ------------------------------------------------------------------ #
+    # Consensus check (internal)
+    # ------------------------------------------------------------------ #
+
+    def _check_consensus(self, b: Belief) -> None:
+        """Update ``b.status`` based on current votes (modifies in place)."""
+        n = len(self.member_names)
+        if n == 0:
+            return
+        ratio_for = len(b.votes_for) / n
+        # A contested belief only un-contests if enough votes_for accumulate.
+        if ratio_for >= self.consensus_threshold:
+            if b.status != "rejected":
+                b.status = "accepted"
+        elif b.status == "accepted":
+            # Acceptance lost (e.g. a new member was added or a vote was removed).
+            b.status = "pending"
+        # Contested status is only cleared by explicit accept calls that move
+        # it to accepted — staying contested is fine.
+
+    # ------------------------------------------------------------------ #
+    # Public API
+    # ------------------------------------------------------------------ #
+
+    def assert_belief(
+        self,
+        claim: str,
+        author: str,
+        confidence: float = 0.5,
+        evidence: str = "",
+    ) -> Belief:
+        """Create a new belief.
+
+        The author implicitly casts an *accept* vote.  Raises
+        :class:`ValueError` if *author* is not in ``member_names``.
+        """
+        belief_id = str(uuid.uuid4())[:8]
+        now = time.time()
+        b = Belief(
+            id=belief_id,
+            claim=claim,
+            author=author,
+            confidence=confidence,
+            evidence=evidence,
+            status="pending",
+            votes_for=[author],
+            votes_against=[],
+            reasons={},
+            created_at=now,
+            updated_at=now,
+        )
+        self._beliefs[belief_id] = b
+        self._check_consensus(b)
+        self._save()
+        return b
+
+    def accept_belief(self, belief_id: str, voter: str) -> Belief:
+        """Cast an *accept* vote for an existing belief.
+
+        Removes any previous *against* vote by the same member.  Re-checks
+        consensus after the vote, which may transition the belief to
+        ``accepted``.  Raises :class:`KeyError` if the belief does not exist.
+        """
+        b = self._beliefs[belief_id]
+        if voter not in b.votes_for:
+            b.votes_for.append(voter)
+        if voter in b.votes_against:
+            b.votes_against.remove(voter)
+        if voter in b.reasons:
+            del b.reasons[voter]
+        b.updated_at = time.time()
+        # Accepting can pull a belief out of contested status.
+        if b.status == "contested":
+            self._check_consensus(b)
+        else:
+            self._check_consensus(b)
+        self._save()
+        return b
+
+    def contest_belief(
+        self,
+        belief_id: str,
+        voter: str,
+        reason: str = "",
+    ) -> Belief:
+        """Contest a belief, moving it to ``contested`` status.
+
+        Any previous *accept* vote by *voter* is removed.  Raises
+        :class:`KeyError` if the belief does not exist.
+        """
+        b = self._beliefs[belief_id]
+        if voter not in b.votes_against:
+            b.votes_against.append(voter)
+        if voter in b.votes_for:
+            b.votes_for.remove(voter)
+        if reason:
+            b.reasons[voter] = reason
+        b.status = "contested"
+        b.updated_at = time.time()
+        self._save()
+        return b
+
+    def reject_belief(self, belief_id: str) -> Belief:
+        """Permanently reject a belief.
+
+        Only useful for orchestrator-level overrides; normally beliefs are
+        contested by individual members rather than rejected outright.
+        """
+        b = self._beliefs[belief_id]
+        b.status = "rejected"
+        b.updated_at = time.time()
+        self._save()
+        return b
+
+    def get_belief(self, belief_id: str) -> Belief | None:
+        """Return the belief with *belief_id*, or ``None``."""
+        return self._beliefs.get(belief_id)
+
+    def list_beliefs(
+        self,
+        status: str | None = None,
+    ) -> list[Belief]:
+        """Return all beliefs, optionally filtered by *status*.
+
+        Results are ordered by recency (most recent first).
+        """
+        results = list(self._beliefs.values())
+        if status:
+            results = [b for b in results if b.status == status]
+        return sorted(results, key=lambda b: b.updated_at, reverse=True)
+
+    def count(self) -> int:
+        """Return the total number of beliefs."""
+        return len(self._beliefs)
+
+    def summary_for_prompt(self, limit: int = 10) -> str:
+        """Compact Markdown summary of the belief board for context injection.
+
+        Returns an empty string when the board is empty.
+        """
+        beliefs = self.list_beliefs()[:limit]
+        if not beliefs:
+            return ""
+        _ICONS: dict[str, str] = {
+            "accepted":  "✓",
+            "contested": "⚡",
+            "rejected":  "✗",
+            "pending":   "?",
+        }
+        lines = [f"## Shared team belief board ({len(beliefs)} entries)"]
+        for b in beliefs:
+            icon = _ICONS.get(b.status, "?")
+            conf = f"{b.confidence:.0%}"
+            lines.append(
+                f"- [{icon}] `{b.id}` {b.claim} "
+                f"(conf: {conf}, by @{b.author}, status: {b.status})"
+            )
+        return "\n".join(lines)
+
+    def to_dict_list(self) -> list[dict[str, Any]]:
+        """Return all beliefs as a list of plain dicts (for serialisation)."""
+        return [asdict(b) for b in self._beliefs.values()]

team/bridge.py

@@ -0,0 +1,197 @@
+"""Cross-team collaboration bridge — protocol layer.
+
+Two ``team`` clusters running on separate machines can collaborate on a
+shared goal through the bridge protocol.  One cluster acts as the *client*
+(it delegates a sub-task) and the other acts as the *server* (it receives
+the task, runs its full team workflow, and returns the results).
+
+Protocol objects
+----------------
+:class:`BridgeTask`
+    Sent by the client when it wants to delegate work.  Carries the goal,
+    an optional free-text context blurb, and any workspace files the remote
+    team needs to start from.
+
+:class:`BridgeResult`
+    Returned by the server.  Contains a free-text summary of what the remote
+    team accomplished, the files it produced, and a status field.
+
+:class:`TaskStore`
+    Server-side, thread-safe registry of in-flight and completed tasks.
+    The HTTP server layer reads and writes through this store.
+
+Wire format
+-----------
+All objects are serialised as plain JSON so any language/tool can interact
+with a bridge server — no shared code required.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+
+# --------------------------------------------------------------------------- #
+# Protocol dataclasses
+# --------------------------------------------------------------------------- #
+
+TaskStatus = Literal["pending", "running", "complete", "error"]
+
+
+@dataclass
+class BridgeTask:
+    """A unit of work delegated from one team cluster to another.
+
+    Parameters
+    ----------
+    goal:
+        What the remote team should accomplish (free text; becomes the
+        ``goal`` for a one-shot Orchestrator run on the server side).
+    context:
+        Optional background information to include in the remote team's
+        kickoff prompt.
+    files:
+        Workspace files to transfer to the remote team, keyed by their
+        relative path.  The server writes them into the remote team's
+        shared workspace before running the workflow.
+    sender:
+        Name of the sending team (informational; logged by the server).
+    task_id:
+        Stable identifier for this task.  Auto-generated if not provided.
+    created_at:
+        Unix timestamp.  Auto-set if not provided.
+    """
+
+    goal: str
+    context: str = ""
+    files: dict[str, str] = field(default_factory=dict)
+    sender: str = "unknown"
+    task_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    created_at: float = field(default_factory=time.time)
+
+    # ------------------------------------------------------------------ #
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "BridgeTask":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class BridgeResult:
+    """The outcome of a delegated task, returned by the bridge server.
+
+    Parameters
+    ----------
+    task_id:
+        Matches the originating :class:`BridgeTask`.
+    status:
+        ``"pending"`` — task queued but not started.
+        ``"running"`` — team workflow in progress.
+        ``"complete"`` — workflow finished; inspect *summary* and *files*.
+        ``"error"``    — workflow raised an exception; inspect *error*.
+    summary:
+        Free-text description of what the remote team accomplished.
+    files:
+        Files produced by the remote team's shared workspace, keyed by
+        relative path.  Written into the local workspace by the client.
+    error:
+        Set when ``status == "error"``; contains the exception message.
+    completed_at:
+        Unix timestamp of when the workflow finished (or ``None``).
+    """
+
+    task_id: str
+    status: TaskStatus = "pending"
+    summary: str = ""
+    files: dict[str, str] = field(default_factory=dict)
+    error: str | None = None
+    completed_at: float | None = None
+
+    # ------------------------------------------------------------------ #
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "BridgeResult":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+# --------------------------------------------------------------------------- #
+# Server-side task store
+# --------------------------------------------------------------------------- #
+
+
+class TaskStore:
+    """Thread-safe registry of tasks and their results.
+
+    The HTTP server layer submits tasks here and workers update them.
+    Clients poll through the same store.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._tasks: dict[str, BridgeTask] = {}
+        self._results: dict[str, BridgeResult] = {}
+
+    # ------------------------------------------------------------------ #
+    # Writing
+    # ------------------------------------------------------------------ #
+
+    def add_task(self, task: BridgeTask) -> None:
+        """Register a new task (status: pending)."""
+        with self._lock:
+            self._tasks[task.task_id] = task
+            self._results[task.task_id] = BridgeResult(
+                task_id=task.task_id, status="pending"
+            )
+
+    def mark_running(self, task_id: str) -> None:
+        with self._lock:
+            if task_id in self._results:
+                self._results[task_id].status = "running"
+
+    def mark_complete(
+        self,
+        task_id: str,
+        summary: str,
+        files: dict[str, str],
+    ) -> None:
+        with self._lock:
+            if task_id in self._results:
+                r = self._results[task_id]
+                r.status = "complete"
+                r.summary = summary
+                r.files = files
+                r.completed_at = time.time()
+
+    def mark_error(self, task_id: str, error: str) -> None:
+        with self._lock:
+            if task_id in self._results:
+                r = self._results[task_id]
+                r.status = "error"
+                r.error = error
+                r.completed_at = time.time()
+
+    # ------------------------------------------------------------------ #
+    # Reading
+    # ------------------------------------------------------------------ #
+
+    def get_task(self, task_id: str) -> BridgeTask | None:
+        with self._lock:
+            return self._tasks.get(task_id)
+
+    def get_result(self, task_id: str) -> BridgeResult | None:
+        with self._lock:
+            return self._results.get(task_id)
+
+    def list_task_ids(self) -> list[str]:
+        with self._lock:
+            return list(self._tasks.keys())

team/bridge_client.py

@@ -0,0 +1,157 @@
+"""Bridge HTTP client — submit tasks to a remote team cluster and collect results.
+
+Usage::
+
+    from team.bridge_client import BridgeClient
+    from team.bridge import BridgeTask
+
+    client = BridgeClient("http://lab-b.example.com:7001")
+
+    task = BridgeTask(
+        goal="Run the survival analysis on the preprocessed BRCA data.",
+        context="Preprocessing complete; data.csv contains 1 142 samples.",
+        files={"data/preprocessed.csv": "<csv content>"},
+        sender="lab-a",
+    )
+
+    task_id = client.submit_task(task)
+    result = client.wait_for_result(task_id, timeout=600)
+
+    if result.status == "complete":
+        for path, content in result.files.items():
+            print(f"received: {path} ({len(content)} chars)")
+    else:
+        print(f"task failed: {result.error}")
+
+All network calls use ``requests`` (already a project dependency) and raise
+:class:`BridgeClientError` on HTTP or connection failures.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+import requests
+
+from team.bridge import BridgeResult, BridgeTask
+
+log = logging.getLogger(__name__)
+
+_DEFAULT_POLL_INTERVAL = 5.0   # seconds between status polls
+_DEFAULT_TIMEOUT = 600         # seconds to wait for a result
+
+
+class BridgeClientError(RuntimeError):
+    """Raised when a bridge HTTP call fails."""
+
+
+class BridgeClient:
+    """HTTP client for the cross-team bridge protocol.
+
+    Parameters
+    ----------
+    base_url:
+        Root URL of the remote bridge server, e.g.
+        ``"http://lab-b.example.com:7001"``.  Trailing slashes are stripped.
+    request_timeout:
+        Per-HTTP-call timeout in seconds (default: 30).
+    """
+
+    def __init__(self, base_url: str, *, request_timeout: int = 30) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._timeout = request_timeout
+
+    # ------------------------------------------------------------------ #
+    # Public API
+    # ------------------------------------------------------------------ #
+
+    def health(self) -> dict:
+        """Return the server's health payload or raise :class:`BridgeClientError`."""
+        return self._get("/health")
+
+    def submit_task(self, task: BridgeTask) -> str:
+        """Submit a task and return the assigned ``task_id``.
+
+        Raises :class:`BridgeClientError` on any HTTP or network error.
+        """
+        resp = self._post("/tasks", task.to_dict())
+        task_id = resp.get("task_id")
+        if not task_id:
+            raise BridgeClientError(f"server returned no task_id: {resp}")
+        log.info("bridge client: submitted task %s to %s", task_id, self.base_url)
+        return task_id
+
+    def poll_result(self, task_id: str) -> BridgeResult:
+        """Fetch the current result/status for *task_id* (single call, no waiting).
+
+        Raises :class:`BridgeClientError` if the task is not found or the
+        server returns an error.
+        """
+        data = self._get(f"/tasks/{task_id}")
+        return BridgeResult.from_dict(data)
+
+    def wait_for_result(
+        self,
+        task_id: str,
+        timeout: float = _DEFAULT_TIMEOUT,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+    ) -> BridgeResult:
+        """Poll until the task reaches a terminal state and return the result.
+
+        Terminal states are ``"complete"`` and ``"error"``.
+
+        Parameters
+        ----------
+        task_id:
+            The task to wait for.
+        timeout:
+            Maximum total seconds to wait before raising :class:`BridgeClientError`.
+        poll_interval:
+            Seconds to sleep between polls (default: 5).
+
+        Raises :class:`BridgeClientError` if the timeout expires or if a
+        network error occurs during polling.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            result = self.poll_result(task_id)
+            log.debug(
+                "bridge client: task %s status=%s", task_id, result.status
+            )
+            if result.status in ("complete", "error"):
+                return result
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise BridgeClientError(
+                    f"timed out waiting for task {task_id!r} after {timeout}s "
+                    f"(last status: {result.status!r})"
+                )
+            time.sleep(min(poll_interval, max(0, remaining)))
+
+    # ------------------------------------------------------------------ #
+    # Low-level HTTP helpers
+    # ------------------------------------------------------------------ #
+
+    def _get(self, path: str) -> dict:
+        url = self.base_url + path
+        try:
+            resp = requests.get(url, timeout=self._timeout)
+            resp.raise_for_status()
+            return resp.json()
+        except requests.RequestException as exc:
+            raise BridgeClientError(f"GET {url} failed: {exc}") from exc
+
+    def _post(self, path: str, payload: dict) -> dict:
+        url = self.base_url + path
+        try:
+            resp = requests.post(
+                url,
+                json=payload,
+                timeout=self._timeout,
+                headers={"Content-Type": "application/json"},
+            )
+            resp.raise_for_status()
+            return resp.json()
+        except requests.RequestException as exc:
+            raise BridgeClientError(f"POST {url} failed: {exc}") from exc