systemg 0.32.0

A simple process manager.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

---
title: Orchestrator
---

# Orchestrator

Multi-agent task execution with cache coordination.

## Overview

Orchestrator supervises agents that claim and execute tasks from a shared cache.

## Architecture

```
Orchestrator → Reads instructions/INSTRUCTIONS.md → Spawns agents → Creates DAGs
Agent → Claims task → Executes → Updates cache
```

Cache keys:
```
dag:<goal>:nodes    # Tasks
dag:<goal>:deps     # Dependencies
task:<id>           # Status
task:<id>:lock      # Locks
agent:<name>:*      # Registry
```

## Features

- **Tasks**: LLM generates DAG from instructions
- **Locking**: Time-limited task leases
- **States**: `BLOCKED → READY → RUNNING → DONE/FAILED`
- **Control**: Heartbeat files accept `PAUSE`, `RESUME`, `DROP-TASK`, etc.
- **Spawning**: Each agent gets instruction file, heartbeat, goal ID

## Files

```
systemg.yaml                    # Orchestrator service config
instructions/INSTRUCTIONS.md    # Agent declarations
instructions/*.md               # Per-agent instructions
instructions/heartbeat/*.md     # Control files
docs/*.md                       # Example specs
```

## Configuration

**systemg.yaml:**
```yaml
version: "1"
services:
  redis:
    command: "redis-server"
  orchestrator:
    command: >
      porki
      --role orchestrator
      --instructions instructions/INSTRUCTIONS.md
      --redis-url redis://127.0.0.1:6379
    env:
      vars:
        PORKI_LLM_MAX_CONCURRENCY: "6"
        PORKI_LLM_CONCURRENCY_WAIT_SECONDS: "900"
    depends_on: ["redis"]
    spawn:
      mode: dynamic
      limit: 10
```

`PORKI_LLM_MAX_CONCURRENCY` raises the number of global LLM leases available
across agents, and `PORKI_LLM_CONCURRENCY_WAIT_SECONDS` controls how long agents
wait for a lease before timing out.

**instructions/INSTRUCTIONS.md:**
```markdown
## Agents
### research_agent
- Goal: goal-001
- Heartbeat: ./instructions/heartbeat/research.md
```

## DAG Format

```json
{
  "goal_id": "goal-001",
  "nodes": [{"id": "task-001", "title": "Research", "priority": 10}],
  "edges": [{"source": "task-001", "target": "task-002"}]
}
```

## Usage

```bash
# Setup
$ cd examples/orchestrator
$ pip install porki

# Run
$ redis-server
$ sysg start

# Monitor
$ sysg logs --service orchestrator
$ redis-cli KEYS "*"

# Control
$ echo "PAUSE" >> ./instructions/heartbeat/research.md
```

## Validation

Use `sysg status`, `sysg logs --service orchestrator`, and Redis keys to validate
runtime behavior. Package-level runtime tests execute in the `porki` repository.

## Links

- [Configuration](/how-it-works/configuration)
- [How It Works](/how-it-works)