Skip to content

README.md

Latest commit

 

History

History
98 lines (81 loc) · 5.39 KB

README.md

File metadata and controls

98 lines (81 loc) · 5.39 KB

DisSysLab user guide

This folder is the user manual for DisSysLab. The top-level README is the place to start — it covers installation, the first office to run, and the framework's core design ideas. Come here after the first office runs successfully, when the question is how do I build my own? or how do I do this specific thing?

The documents below assume DisSysLab is already installed and that dsl run periodic_brief produced a brief on your terminal.

Where to start

A reader new to DisSysLab will find the path of least friction is:

  1. Run periodic_brief and a second office from the gallery. Two examples are enough to recognise the structure of an office.
  2. Read BUILD_APPS.md, which works through the full grammar of office.md and a substantial example role.
  3. Browse SOURCES_AND_SINKS.md for sources and sinks the framework ships with. Most new offices can be assembled from existing components.
  4. Edit a copy of a gallery office (dsl init <name> my_office) and modify it until it does what you want. Many users never need to write an office from scratch.

When something does not work, TROUBLESHOOTING.md indexes the common errors by their exact text. The command dsl doctor runs the same checks live in your terminal.

Documents in this folder

Document Subject When to read
BUILD_APPS.md Designing and wiring your own office, from idea to running system. Includes the full office.md grammar and a worked example of a substantial role. Before writing your first office from scratch.
SOURCES_AND_SINKS.md Every source and sink component the framework ships with, with arguments, environment variables, and setup notes. Reference. Consult before writing a custom source or sink.
LANGUAGE_MODELS.md Choosing and mixing LLM backends (anthropic, openai, gemini, openrouter, ollama), per-role backend overrides, named variants (_creative, _precise), and the Backend Protocol for adding a new provider. Before changing the office's AI engine or adding a new provider.
PATTERN_sense_think_respond.md The canonical multi-stage pattern that most gallery offices instantiate. Includes a Python helper for generating new instances of the pattern. When the office you want resembles sense → think → respond.
MAKE_OFFICE.md The Python API for generating offices programmatically rather than writing office.md by hand. When a tool or script needs to produce offices. Most users do not need this.
TROUBLESHOOTING.md Error messages from dsl run and dsl build, with the cause and the remedy for each. When something goes wrong. The companion command is dsl doctor.

Recipes

The recipes/ folder holds short, copy-pasteable solutions to common tasks. Each recipe edits one or two plain English files — typically an office.md and a role under roles/:

Recipe What it does
Filter for a topic Keep items that mention something specific, discard the rest.
Monitor your inbox Turn Gmail messages into briefings, with App Password setup.
Receive webhooks Listen on a local port for posts from GitHub, Stripe, Zapier, or your own scripts.
Send messages outside Forward briefings to email, Slack, a webhook, or a JSONL file.
Add an RSS source Read items from any RSS or Atom feed.
Chain offices Let one office's output flow into another.
Write a custom role Describe a new job in plain English and assign it to an agent.

Lookup by task

For frequently asked questions, the relevant section of the documentation is named below.

If a question is not answered here, please open an issue on GitHub. Gaps in the documentation are easier to fix when they are reported.

Notes used during the development of the framework itself, rather than for running offices, live in the dev/ folder at the repo root. Those notes change frequently and are not part of the user guide.