dissyslab 1.0.2__tar.gz

dissyslab-1.0.2/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2025 K. Mani Chandy
+
+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...

dissyslab-1.0.2/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: dissyslab
+Version: 1.0.2
+Summary: DisSysLab — build continuous offices of AI agents in plain English.
+Author-email: "K. Mani Chandy" <kmchandy@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kmchandy/DisSysLab
+Project-URL: Source, https://github.com/kmchandy/DisSysLab
+Project-URL: Documentation, https://github.com/kmchandy/DisSysLab#readme
+Project-URL: Issues, https://github.com/kmchandy/DisSysLab/issues
+Keywords: distributed-systems,agents,ai,education,claude,anthropic,llm,dataflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.39.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: feedparser>=6.0.11
+Requires-Dist: requests>=2.31.0
+Requires-Dist: websocket-client>=1.6.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
+Requires-Dist: ruff>=0.6.9; extra == "dev"
+Requires-Dist: black>=24.8.0; extra == "dev"
+Requires-Dist: build>=1.2.1; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Dynamic: license-file
+
+# DSL — Build Your Own Office of AI Agents
+
+**AI tools answer when you ask. What if a network of AI agents worked for you all the time?**
+
+## 🎓 New to DisSysLab? Start here
+[Take the 5-minute micro-course](https://kmchandy.github.io/DisSysLab/office_microcourse.html)
+
+Then read [Getting started](GETTING_STARTED.md)
+
+---
+
+DSL lets you build an office of AI agents that runs continuously and never stops
+until you tell it to.
+Your agents monitor sources, analyze data, control devices, and store results for you, all
+the time.
+
+---
+
+![Situation Room](gallery/org_situation_room/screenshot.png)
+
+*A Situation Room scanning live news and social media in real time.
+You didn't write any code. You wrote two plain English documents.*
+
+---
+
+## Get Started in 3 Commands
+
+```bash
+git clone https://github.com/kmchandy/DisSysLab.git && cd DisSysLab
+pip install -e .
+export ANTHROPIC_API_KEY='your-key'
+
+dsl run gallery/org_intelligence_briefing/
+```
+
+`pip install -e .` installs DisSysLab in editable mode and puts the
+`dsl` command on your PATH. `dsl run` reads your plain English files,
+shows you the routing, asks "Does this look right?", and starts your
+office. Run `dsl doctor` first if you want to check your setup, or
+`dsl gallery` to browse the offices that ship with the repo.
+
+---
+
+## Two Paths Forward
+
+### Path A — Describe your office in plain English: Job Descriptions and Org Chart
+
+You write job descriptions and an org chart. No programming required.
+
+**The job descriptions — what each agent does:**
+
+```
+# Role: analyst
+
+You are a news analyst who receives posts and articles and sends
+items to an editor or a discard.
+
+Your job is to decide if each item is relevant to significant
+political developments or economic events — specifically involving
+topics such as Trump, Congress, Senate, elections, the Federal Reserve,
+tariffs, inflation, markets, Ukraine, Iran, trade policy, or the
+broader economy.
+
+Exclude celebrity gossip, sports, entertainment, and personal
+opinions with no broader political or economic significance.
+
+If the item is relevant, send to editor.
+Otherwise send to discard.
+```
+
+```
+# Role: editor
+
+You are a senior editor who receives posts and articles and sends
+items to a situation_room.
+
+Your job is to rate each item for its significance — CRITICAL, HIGH,
+MEDIUM, or LOW — and rewrite it as a crisp one-paragraph briefing note.
+Note whether the item came from social media or news. Preserve the
+source, url, timestamp, and author fields. Put your significance rating
+in a field called "significance" and your summary in the "text" field.
+
+Always send results to situation_room.
+```
+
+**The org chart — who connects to whom:**
+
+```
+Sources: bluesky(max_posts=None, lifetime=None),
+         al_jazeera(max_articles=10, poll_interval=600),
+         bbc_world(max_articles=10, poll_interval=600)
+Sinks: intelligence_display(max_items=8),
+       jsonl_recorder(path="situation_room.jsonl")
+
+Agents:
+Alex is an analyst.
+Morgan is an editor.
+
+Connections:
+bluesky's destination is Alex.
+al_jazeera's destination is Alex.
+bbc_world's destination is Alex.
+Alex's editor is Morgan.
+Alex's discard is jsonl_recorder.
+Morgan's situation_room are intelligence_display and jsonl_recorder.
+```
+
+That's it. Change the topics, change the agents, change the sources.
+The office is yours.
+
+**Offices can contain offices.** An office is
+a building block which you can put into a network with other offices
+— a news office feeding a strategy office, a research
+office feeding an editorial office. Each office is a black box: the
+organization only knows what goes in and what comes out. You can build
+organizations of arbitrary complexity, one office at a time, reusing
+offices across different networks.
+
+**→ [Go to the gallery](gallery/README.md) to run an existing office and build your own.**
+
+---
+
+### Path B — Learn how distributed systems work
+
+**Interested in how DSL works under the hood?** 
+DSL is also a  Python framework for building distributed systems —
+concurrent agents, message queues, routing, and termination detection.
+See [`examples/`](examples/README.md) for a module sequence that takes you 
+from your first network to building distributed systems from scratch.
+
+---
+
+## Requirements
+
+- Python 3.9+
+- Anthropic API key ([get one here](https://console.anthropic.com))
+- Install with `pip install -e .` from this repo (or `pip install -r requirements.txt` if you only want the dependencies without the `dsl` command)
+
+---
+
+*DSL is an open research project exploring natural language interfaces
+to persistent distributed systems.*

dissyslab-1.0.2/README.md

@@ -0,0 +1,142 @@
+# DSL — Build Your Own Office of AI Agents
+
+**AI tools answer when you ask. What if a network of AI agents worked for you all the time?**
+
+## 🎓 New to DisSysLab? Start here
+[Take the 5-minute micro-course](https://kmchandy.github.io/DisSysLab/office_microcourse.html)
+
+Then read [Getting started](GETTING_STARTED.md)
+
+---
+
+DSL lets you build an office of AI agents that runs continuously and never stops
+until you tell it to.
+Your agents monitor sources, analyze data, control devices, and store results for you, all
+the time.
+
+---
+
+![Situation Room](gallery/org_situation_room/screenshot.png)
+
+*A Situation Room scanning live news and social media in real time.
+You didn't write any code. You wrote two plain English documents.*
+
+---
+
+## Get Started in 3 Commands
+
+```bash
+git clone https://github.com/kmchandy/DisSysLab.git && cd DisSysLab
+pip install -e .
+export ANTHROPIC_API_KEY='your-key'
+
+dsl run gallery/org_intelligence_briefing/
+```
+
+`pip install -e .` installs DisSysLab in editable mode and puts the
+`dsl` command on your PATH. `dsl run` reads your plain English files,
+shows you the routing, asks "Does this look right?", and starts your
+office. Run `dsl doctor` first if you want to check your setup, or
+`dsl gallery` to browse the offices that ship with the repo.
+
+---
+
+## Two Paths Forward
+
+### Path A — Describe your office in plain English: Job Descriptions and Org Chart
+
+You write job descriptions and an org chart. No programming required.
+
+**The job descriptions — what each agent does:**
+
+```
+# Role: analyst
+
+You are a news analyst who receives posts and articles and sends
+items to an editor or a discard.
+
+Your job is to decide if each item is relevant to significant
+political developments or economic events — specifically involving
+topics such as Trump, Congress, Senate, elections, the Federal Reserve,
+tariffs, inflation, markets, Ukraine, Iran, trade policy, or the
+broader economy.
+
+Exclude celebrity gossip, sports, entertainment, and personal
+opinions with no broader political or economic significance.
+
+If the item is relevant, send to editor.
+Otherwise send to discard.
+```
+
+```
+# Role: editor
+
+You are a senior editor who receives posts and articles and sends
+items to a situation_room.
+
+Your job is to rate each item for its significance — CRITICAL, HIGH,
+MEDIUM, or LOW — and rewrite it as a crisp one-paragraph briefing note.
+Note whether the item came from social media or news. Preserve the
+source, url, timestamp, and author fields. Put your significance rating
+in a field called "significance" and your summary in the "text" field.
+
+Always send results to situation_room.
+```
+
+**The org chart — who connects to whom:**
+
+```
+Sources: bluesky(max_posts=None, lifetime=None),
+         al_jazeera(max_articles=10, poll_interval=600),
+         bbc_world(max_articles=10, poll_interval=600)
+Sinks: intelligence_display(max_items=8),
+       jsonl_recorder(path="situation_room.jsonl")
+
+Agents:
+Alex is an analyst.
+Morgan is an editor.
+
+Connections:
+bluesky's destination is Alex.
+al_jazeera's destination is Alex.
+bbc_world's destination is Alex.
+Alex's editor is Morgan.
+Alex's discard is jsonl_recorder.
+Morgan's situation_room are intelligence_display and jsonl_recorder.
+```
+
+That's it. Change the topics, change the agents, change the sources.
+The office is yours.
+
+**Offices can contain offices.** An office is
+a building block which you can put into a network with other offices
+— a news office feeding a strategy office, a research
+office feeding an editorial office. Each office is a black box: the
+organization only knows what goes in and what comes out. You can build
+organizations of arbitrary complexity, one office at a time, reusing
+offices across different networks.
+
+**→ [Go to the gallery](gallery/README.md) to run an existing office and build your own.**
+
+---
+
+### Path B — Learn how distributed systems work
+
+**Interested in how DSL works under the hood?** 
+DSL is also a  Python framework for building distributed systems —
+concurrent agents, message queues, routing, and termination detection.
+See [`examples/`](examples/README.md) for a module sequence that takes you 
+from your first network to building distributed systems from scratch.
+
+---
+
+## Requirements
+
+- Python 3.9+
+- Anthropic API key ([get one here](https://console.anthropic.com))
+- Install with `pip install -e .` from this repo (or `pip install -r requirements.txt` if you only want the dependencies without the `dsl` command)
+
+---
+
+*DSL is an open research project exploring natural language interfaces
+to persistent distributed systems.*

dissyslab-1.0.2/dissyslab/__init__.py

@@ -0,0 +1,25 @@
+# dissyslab/__init__.py
+"""
+DisSysLab - Distributed Systems Teaching Framework
+
+Public API exports.
+"""
+
+from dissyslab.core import Agent, ExceptionThread
+from dissyslab.network import Network
+from dissyslab.builder import network, PortReference
+
+__all__ = [
+    # Core
+    'Agent',
+    'ExceptionThread',
+
+    # Network
+    'Network',
+    'network',
+
+    # Builder
+    'PortReference',
+]
+
+__version__ = '1.0.2'

dissyslab-1.0.2/dissyslab/blocks/__init__.py

@@ -0,0 +1,32 @@
+# dissyslab/blocks/__init__.py
+"""
+Standard agent blocks for building distributed systems.
+
+Available blocks:
+- Source: Generate messages (no inputs)
+- Transform: Process messages (one input, one output)
+- Sink: Consume messages (one input, no outputs)
+- Broadcast: Fanout - copy message to multiple outputs
+- MergeAsynch: Fanin - merge multiple inputs into one stream
+- Split: Content-based routing to multiple outputs
+"""
+
+from dissyslab.blocks.source import Source
+from dissyslab.blocks.transform import Transform
+from dissyslab.blocks.sink import Sink
+from dissyslab.blocks.fanout import Broadcast
+from dissyslab.blocks.fanin import MergeAsynch
+from dissyslab.blocks.merge_synch import MergeSynch
+from dissyslab.blocks.split import Split
+from dissyslab.blocks.role import Role
+
+__all__ = [
+    "Source",
+    "Transform",
+    "Sink",
+    "Broadcast",
+    "MergeAsynch",
+    "MergeSynch",
+    "Split",
+    "Role",
+]

dissyslab-1.0.2/dissyslab/blocks/fanin.py

@@ -0,0 +1,90 @@
+# dissyslab/blocks/fanin.py
+"""
+Merge Agents: Combine multiple inputs into single output (fanin).
+
+MergeAsynch is the recommended merge for most use cases. Termination is
+signaled by os_agent via _Shutdown, handled transparently by recv().
+No STOP coordination needed.
+"""
+
+from __future__ import annotations
+from typing import Optional
+import threading
+
+from dissyslab.core import Agent, _ShutdownSignal
+
+
+class MergeAsynch(Agent):
+    """
+    MergeAsynch agent: combines multiple inputs (fanin, non-deterministic).
+
+    Multiple inputs, single output. Receives from whichever input has
+    a message available first. Fast but non-deterministic order.
+
+    **Ports:**
+    - Inports: ["in_0", "in_1", ..., "in_{n-1}"]
+    - Outports: ["out_"]
+
+    **Termination:**
+    Termination is detected by os_agent and signaled via _Shutdown on
+    each inport, handled transparently by recv(). No STOP coordination
+    needed — worker threads exit cleanly via _ShutdownSignal.
+    """
+
+    def __init__(self, *, num_inputs: int, name: Optional[str] = None):
+        if num_inputs < 1:
+            raise ValueError(
+                f"MergeAsynch requires at least 1 input, got {num_inputs}"
+            )
+
+        inports = [f"in_{i}" for i in range(num_inputs)]
+        super().__init__(name=name, inports=inports, outports=["out_"])
+        self.num_inputs = num_inputs
+
+    @property
+    def default_inport(self) -> Optional[str]:
+        """No default input (multiple inputs - ambiguous)."""
+        return None
+
+    @property
+    def default_outport(self) -> str:
+        """Default output port for edge syntax."""
+        return "out_"
+
+    def _worker(self, port: str) -> None:
+        """
+        Worker thread for one input port.
+        Forwards messages to out_ until _ShutdownSignal is raised by recv().
+        """
+        try:
+            while True:
+                msg = self.recv(port)
+                self.send(msg, "out_")
+        except _ShutdownSignal:
+            pass  # clean exit — os_agent declared termination
+
+    def run(self) -> None:
+        """
+        Spawn one worker thread per input port and wait for all to finish.
+
+        Workers exit when recv() raises _ShutdownSignal on _Shutdown receipt.
+        """
+        threads = []
+        for p in self.inports:
+            t = threading.Thread(
+                target=self._worker,
+                args=(p,),
+                name=f"merge_worker_{p}",
+                daemon=False
+            )
+            t.start()
+            threads.append(t)
+
+        for t in threads:
+            t.join()
+
+    def __repr__(self) -> str:
+        return f"<MergeAsynch name={self.name} inputs={self.num_inputs}>"
+
+    def __str__(self) -> str:
+        return f"MergeAsynch({self.num_inputs} inputs)"

dissyslab-1.0.2/dissyslab/blocks/fanout.py

@@ -0,0 +1,69 @@
+# dissyslab/blocks/fanout.py
+"""
+Broadcast Agent: Copies messages to multiple outputs (fanout).
+
+Broadcast agents are automatically inserted by the framework when one
+agent connects to multiple receivers. Termination is signaled by os_agent
+via _Shutdown, handled transparently by recv().
+"""
+
+from __future__ import annotations
+from typing import Optional
+import copy
+
+from dissyslab.core import Agent
+
+
+class Broadcast(Agent):
+    """
+    Broadcast agent: copies messages to multiple outputs (fanout).
+
+    Single input, multiple outputs. Receives message and sends a deep
+    copy to each output port.
+
+    **Ports:**
+    - Inports: ["in_"]
+    - Outports: ["out_0", "out_1", ..., "out_{n-1}"]
+
+    **Termination:**
+    Termination is detected by os_agent and signaled via _Shutdown,
+    which recv() handles transparently by raising _ShutdownSignal.
+    """
+
+    def __init__(self, *, num_outputs: int, name: Optional[str] = None):
+        if num_outputs < 1:
+            raise ValueError(
+                f"Broadcast requires at least 1 output, got {num_outputs}"
+            )
+
+        outports = [f"out_{i}" for i in range(num_outputs)]
+        super().__init__(name=name, inports=["in_"], outports=outports)
+        self.num_outputs = num_outputs
+
+    @property
+    def default_inport(self) -> str:
+        """Default input port for edge syntax."""
+        return "in_"
+
+    @property
+    def default_outport(self) -> Optional[str]:
+        """No default output (multiple outputs - ambiguous)."""
+        return None
+
+    def run(self) -> None:
+        """
+        Broadcast messages to all outputs.
+
+        recv() intercepts _Shutdown and raises _ShutdownSignal,
+        which unwinds this loop cleanly.
+        """
+        while True:
+            msg = self.recv("in_")
+            for i in range(self.num_outputs):
+                self.send(copy.deepcopy(msg), f"out_{i}")
+
+    def __repr__(self) -> str:
+        return f"<Broadcast name={self.name} outputs={self.num_outputs}>"
+
+    def __str__(self) -> str:
+        return f"Broadcast({self.num_outputs} outputs)"

dissyslab-1.0.2/dissyslab/blocks/merge_synch.py

@@ -0,0 +1,73 @@
+# dissyslab/blocks/merge_synch.py
+"""
+Merge Agents: Combine multiple inputs into single output.
+
+MergeSynch: Synchronous merge in round-robin order (use sparingly).
+For most use cases, prefer MergeAsynch in fanin.py.
+
+Termination is signaled by os_agent via _Shutdown, handled transparently
+by recv(). No explicit STOP handling needed.
+"""
+
+from __future__ import annotations
+from typing import Optional
+
+from dissyslab.core import Agent
+
+
+class MergeSynch(Agent):
+    """
+    MergeSynch agent: synchronously combines multiple inputs in round-robin order.
+
+    **WARNING: Use only when deterministic ordering is required AND all inputs
+    produce messages at similar rates. For most use cases, prefer MergeAsynch.**
+
+    **Ports:**
+    - Inports: ["in_0", "in_1", ..., "in_{n-1}"]
+    - Outports: ["out_"]
+
+    **Termination:**
+    Termination is detected by os_agent and signaled via _Shutdown,
+    which recv() handles transparently by raising _ShutdownSignal.
+    """
+
+    def __init__(self, *, num_inputs: int, name: Optional[str] = None):
+        if num_inputs < 1:
+            raise ValueError(
+                f"MergeSynch requires at least 1 input, got {num_inputs}"
+            )
+
+        inports = [f"in_{i}" for i in range(num_inputs)]
+        super().__init__(name=name, inports=inports, outports=["out_"])
+        self.num_inputs = num_inputs
+
+    @property
+    def default_inport(self) -> Optional[str]:
+        """No default input (multiple inputs - ambiguous)."""
+        return None
+
+    @property
+    def default_outport(self) -> str:
+        """Default output port for edge syntax."""
+        return "out_"
+
+    def run(self) -> None:
+        """
+        Synchronous merge loop: collect batches in round-robin order.
+
+        Collects one message from each input in order, sends as a list.
+        recv() intercepts _Shutdown and raises _ShutdownSignal,
+        which unwinds this loop cleanly.
+        """
+        while True:
+            batch = []
+            for inport in self.inports:
+                msg = self.recv(inport)
+                batch.append(msg)
+            self.send(batch, "out_")
+
+    def __repr__(self) -> str:
+        return f"<MergeSynch name={self.name} inputs={self.num_inputs}>"
+
+    def __str__(self) -> str:
+        return f"MergeSynch({self.num_inputs} inputs)"