ouroboros-ai 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of ouroboros-ai might be problematic. Click here for more details.
- ouroboros/__init__.py +15 -0
- ouroboros/__main__.py +9 -0
- ouroboros/bigbang/__init__.py +39 -0
- ouroboros/bigbang/ambiguity.py +464 -0
- ouroboros/bigbang/interview.py +530 -0
- ouroboros/bigbang/seed_generator.py +610 -0
- ouroboros/cli/__init__.py +9 -0
- ouroboros/cli/commands/__init__.py +7 -0
- ouroboros/cli/commands/config.py +79 -0
- ouroboros/cli/commands/init.py +425 -0
- ouroboros/cli/commands/run.py +201 -0
- ouroboros/cli/commands/status.py +85 -0
- ouroboros/cli/formatters/__init__.py +31 -0
- ouroboros/cli/formatters/panels.py +157 -0
- ouroboros/cli/formatters/progress.py +112 -0
- ouroboros/cli/formatters/tables.py +166 -0
- ouroboros/cli/main.py +60 -0
- ouroboros/config/__init__.py +81 -0
- ouroboros/config/loader.py +292 -0
- ouroboros/config/models.py +332 -0
- ouroboros/core/__init__.py +62 -0
- ouroboros/core/ac_tree.py +401 -0
- ouroboros/core/context.py +472 -0
- ouroboros/core/errors.py +246 -0
- ouroboros/core/seed.py +212 -0
- ouroboros/core/types.py +205 -0
- ouroboros/evaluation/__init__.py +110 -0
- ouroboros/evaluation/consensus.py +350 -0
- ouroboros/evaluation/mechanical.py +351 -0
- ouroboros/evaluation/models.py +235 -0
- ouroboros/evaluation/pipeline.py +286 -0
- ouroboros/evaluation/semantic.py +302 -0
- ouroboros/evaluation/trigger.py +278 -0
- ouroboros/events/__init__.py +5 -0
- ouroboros/events/base.py +80 -0
- ouroboros/events/decomposition.py +153 -0
- ouroboros/events/evaluation.py +248 -0
- ouroboros/execution/__init__.py +44 -0
- ouroboros/execution/atomicity.py +451 -0
- ouroboros/execution/decomposition.py +481 -0
- ouroboros/execution/double_diamond.py +1386 -0
- ouroboros/execution/subagent.py +275 -0
- ouroboros/observability/__init__.py +63 -0
- ouroboros/observability/drift.py +383 -0
- ouroboros/observability/logging.py +504 -0
- ouroboros/observability/retrospective.py +338 -0
- ouroboros/orchestrator/__init__.py +78 -0
- ouroboros/orchestrator/adapter.py +391 -0
- ouroboros/orchestrator/events.py +278 -0
- ouroboros/orchestrator/runner.py +597 -0
- ouroboros/orchestrator/session.py +486 -0
- ouroboros/persistence/__init__.py +23 -0
- ouroboros/persistence/checkpoint.py +511 -0
- ouroboros/persistence/event_store.py +183 -0
- ouroboros/persistence/migrations/__init__.py +1 -0
- ouroboros/persistence/migrations/runner.py +100 -0
- ouroboros/persistence/migrations/scripts/001_initial.sql +20 -0
- ouroboros/persistence/schema.py +56 -0
- ouroboros/persistence/uow.py +230 -0
- ouroboros/providers/__init__.py +28 -0
- ouroboros/providers/base.py +133 -0
- ouroboros/providers/claude_code_adapter.py +212 -0
- ouroboros/providers/litellm_adapter.py +316 -0
- ouroboros/py.typed +0 -0
- ouroboros/resilience/__init__.py +67 -0
- ouroboros/resilience/lateral.py +595 -0
- ouroboros/resilience/stagnation.py +727 -0
- ouroboros/routing/__init__.py +60 -0
- ouroboros/routing/complexity.py +272 -0
- ouroboros/routing/downgrade.py +664 -0
- ouroboros/routing/escalation.py +340 -0
- ouroboros/routing/router.py +204 -0
- ouroboros/routing/tiers.py +247 -0
- ouroboros/secondary/__init__.py +40 -0
- ouroboros/secondary/scheduler.py +467 -0
- ouroboros/secondary/todo_registry.py +483 -0
- ouroboros_ai-0.1.0.dist-info/METADATA +607 -0
- ouroboros_ai-0.1.0.dist-info/RECORD +81 -0
- ouroboros_ai-0.1.0.dist-info/WHEEL +4 -0
- ouroboros_ai-0.1.0.dist-info/entry_points.txt +2 -0
- ouroboros_ai-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,607 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ouroboros-ai
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Self-Improving AI Workflow System
|
|
5
|
+
Author-email: Q00 <jqyu.lee@gmail.com>
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Python: >=3.14
|
|
8
|
+
Requires-Dist: aiosqlite>=0.20.0
|
|
9
|
+
Requires-Dist: claude-agent-sdk>=0.1.0
|
|
10
|
+
Requires-Dist: httpx>=0.27.0
|
|
11
|
+
Requires-Dist: litellm>=1.80.0
|
|
12
|
+
Requires-Dist: pydantic>=2.0.0
|
|
13
|
+
Requires-Dist: pyyaml>=6.0.0
|
|
14
|
+
Requires-Dist: rich>=13.0.0
|
|
15
|
+
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
|
|
16
|
+
Requires-Dist: stamina>=25.1.0
|
|
17
|
+
Requires-Dist: structlog>=24.0.0
|
|
18
|
+
Requires-Dist: typer>=0.12.0
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
<p align="center">
|
|
22
|
+
<br/>
|
|
23
|
+
<br/>
|
|
24
|
+
<br/>
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
<h1 align="center">
|
|
28
|
+
<br/>
|
|
29
|
+
◯ ─────────── ◯
|
|
30
|
+
<br/>
|
|
31
|
+
<br/>
|
|
32
|
+
O U R O B O R O S
|
|
33
|
+
<br/>
|
|
34
|
+
<br/>
|
|
35
|
+
◯ ─────────── ◯
|
|
36
|
+
<br/>
|
|
37
|
+
<br/>
|
|
38
|
+
</h1>
|
|
39
|
+
|
|
40
|
+
<p align="center">
|
|
41
|
+
<em>The serpent that devours itself to be reborn anew.</em>
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
<p align="center">
|
|
45
|
+
<a href="#-philosophy">Philosophy</a> •
|
|
46
|
+
<a href="#-the-six-phases">Phases</a> •
|
|
47
|
+
<a href="#-architecture">Architecture</a> •
|
|
48
|
+
<a href="#-quick-start">Start</a> •
|
|
49
|
+
<a href="#-the-personas-lateral-thinking-agents">Personas</a>
|
|
50
|
+
</p>
|
|
51
|
+
|
|
52
|
+
<br/>
|
|
53
|
+
|
|
54
|
+
<p align="center">
|
|
55
|
+
<code>73 modules</code> · <code>1,292 tests</code> · <code>97%+ coverage</code>
|
|
56
|
+
</p>
|
|
57
|
+
|
|
58
|
+
<br/>
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
<br/>
|
|
63
|
+
|
|
64
|
+
## ◈ The Premise
|
|
65
|
+
|
|
66
|
+
<br/>
|
|
67
|
+
|
|
68
|
+
<table>
|
|
69
|
+
<tr>
|
|
70
|
+
<td width="100%">
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
╔════════════════════════════════════════════════════════╗
|
|
74
|
+
║ ║
|
|
75
|
+
║ 「 HUMANS ARE NOT RATIONAL 」 ║
|
|
76
|
+
║ ║
|
|
77
|
+
╚════════════════════════════════════════════════════════╝
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
</td>
|
|
81
|
+
</tr>
|
|
82
|
+
</table>
|
|
83
|
+
|
|
84
|
+
Human requirements arrive **ambiguous**, **incomplete**, **contradictory**, and **surface-level**.
|
|
85
|
+
|
|
86
|
+
If AI executes such input directly → `GIGO` (Garbage In, Garbage Out).
|
|
87
|
+
|
|
88
|
+
<br/>
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
<br/>
|
|
93
|
+
|
|
94
|
+
## ◈ Philosophy
|
|
95
|
+
|
|
96
|
+
<br/>
|
|
97
|
+
|
|
98
|
+
### The Two Ancient Methods
|
|
99
|
+
|
|
100
|
+
To transmute irrational input into executable truth, we invoke:
|
|
101
|
+
|
|
102
|
+
<br/>
|
|
103
|
+
|
|
104
|
+
<table>
|
|
105
|
+
<tr>
|
|
106
|
+
<td width="50%" valign="top">
|
|
107
|
+
|
|
108
|
+
#### ⌬ SOCRATIC QUESTIONING
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
"Why do you want this?"
|
|
112
|
+
|
|
113
|
+
"What if you don't get it?"
|
|
114
|
+
|
|
115
|
+
"Is that truly necessary?"
|
|
116
|
+
|
|
117
|
+
"What are you assuming?"
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
↳ *Reveals hidden assumptions* <br/>
|
|
121
|
+
↳ *Exposes contradictions* <br/>
|
|
122
|
+
↳ *Challenges the obvious* <br/>
|
|
123
|
+
|
|
124
|
+
</td>
|
|
125
|
+
<td width="50%" valign="top">
|
|
126
|
+
|
|
127
|
+
#### ⌬ ONTOLOGICAL ANALYSIS
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
"What IS this, really?"
|
|
131
|
+
|
|
132
|
+
"Symptom or root cause?"
|
|
133
|
+
|
|
134
|
+
"What's the essence?"
|
|
135
|
+
|
|
136
|
+
"What must exist first?"
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
↳ *Finds the root problem* <br/>
|
|
140
|
+
↳ *Separates essential from accidental* <br/>
|
|
141
|
+
↳ *Maps the structure of being* <br/>
|
|
142
|
+
|
|
143
|
+
</td>
|
|
144
|
+
</tr>
|
|
145
|
+
</table>
|
|
146
|
+
|
|
147
|
+
<br/>
|
|
148
|
+
|
|
149
|
+
These iterate until a **Seed** crystallizes—a specification with `Ambiguity ≤ 0.2`.
|
|
150
|
+
|
|
151
|
+
*Only then does execution begin. Only then can it succeed.*
|
|
152
|
+
|
|
153
|
+
<br/>
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
<br/>
|
|
158
|
+
|
|
159
|
+
### The Governing Principle
|
|
160
|
+
|
|
161
|
+
<br/>
|
|
162
|
+
|
|
163
|
+
<table>
|
|
164
|
+
<tr>
|
|
165
|
+
<td width="100%">
|
|
166
|
+
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
╭────────────────────────────────────────────────────────────╮
|
|
170
|
+
│ │
|
|
171
|
+
│ │
|
|
172
|
+
│ 「 FRUGAL BY DEFAULT, RIGOROUS IN VERIFICATION 」 │
|
|
173
|
+
│ │
|
|
174
|
+
│ │
|
|
175
|
+
╰────────────────────────────────────────────────────────────╯
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
</td>
|
|
181
|
+
</tr>
|
|
182
|
+
</table>
|
|
183
|
+
|
|
184
|
+
<br/>
|
|
185
|
+
|
|
186
|
+
| Paradox | Problem | Ouroboros Solution |
|
|
187
|
+
|---------|---------|-------------------|
|
|
188
|
+
| Power without Wisdom | Frontier models cost 30x | Start at 1x, escalate only when needed |
|
|
189
|
+
| Speed without Judgment | Fast models miss nuance | 3-stage evaluation catches errors |
|
|
190
|
+
| Iteration without Direction | Infinite loops | Drift detection + Retrospective |
|
|
191
|
+
|
|
192
|
+
<br/>
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
<br/>
|
|
197
|
+
|
|
198
|
+
## ◈ The Six Phases
|
|
199
|
+
|
|
200
|
+
<br/>
|
|
201
|
+
|
|
202
|
+
```
|
|
203
|
+
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
204
|
+
┃ ┃
|
|
205
|
+
┃ ┃
|
|
206
|
+
┃ ┌─────────┐ ┃
|
|
207
|
+
┃ │ PHASE 0 │ B I G B A N G ┃
|
|
208
|
+
┃ └────┬────┘ ┃
|
|
209
|
+
┃ │ Socratic + Ontological questioning ┃
|
|
210
|
+
┃ │ From irrational chaos → crystallized Seed ┃
|
|
211
|
+
┃ │ Gate: Ambiguity ≤ 0.2 ┃
|
|
212
|
+
┃ ▼ ┃
|
|
213
|
+
┃ ┌─────────┐ ┃
|
|
214
|
+
┃ │ PHASE 1 │ P A L R O U T E R ┃
|
|
215
|
+
┃ └────┬────┘ ┃
|
|
216
|
+
┃ │ Progressive Adaptive LLM selection ┃
|
|
217
|
+
┃ │ 1x (Frugal) → 10x (Standard) → 30x (Frontier) ┃
|
|
218
|
+
┃ │ "Choose your weapon wisely" ┃
|
|
219
|
+
┃ ▼ ┃
|
|
220
|
+
┃ ┌─────────┐ ┃
|
|
221
|
+
┃ │ PHASE 2 │ D O U B L E D I A M O N D ┃
|
|
222
|
+
┃ └────┬────┘ ┃
|
|
223
|
+
┃ │ Discover → Define → Design → Deliver ┃
|
|
224
|
+
┃ │ Diverge to explore, converge to execute ┃
|
|
225
|
+
┃ │ Recursive decomposition until atomic ┃
|
|
226
|
+
┃ ▼ ┃
|
|
227
|
+
┃ ┌─────────┐ ┃
|
|
228
|
+
┃ │ PHASE 3 │ R E S I L I E N C E ┃
|
|
229
|
+
┃ └────┬────┘ ┃
|
|
230
|
+
┃ │ Stagnation detection (4 patterns) ┃
|
|
231
|
+
┃ │ Lateral thinking via persona rotation ┃
|
|
232
|
+
┃ │ "When stuck, think sideways" ┃
|
|
233
|
+
┃ ▼ ┃
|
|
234
|
+
┃ ┌─────────┐ ┃
|
|
235
|
+
┃ │ PHASE 4 │ E V A L U A T I O N ┃
|
|
236
|
+
┃ └────┬────┘ ┃
|
|
237
|
+
┃ │ Stage 1: Mechanical ($0) — lint, build, test ┃
|
|
238
|
+
┃ │ Stage 2: Semantic ($$) — AC compliance, drift ┃
|
|
239
|
+
┃ │ Stage 3: Consensus ($$$$) — multi-model vote ┃
|
|
240
|
+
┃ ▼ ┃
|
|
241
|
+
┃ ┌─────────┐ ┃
|
|
242
|
+
┃ │ PHASE 5 │ S E C O N D A R Y L O O P ┃
|
|
243
|
+
┃ └────┬────┘ ┃
|
|
244
|
+
┃ │ TODO Registry: defer the trivial ┃
|
|
245
|
+
┃ │ Batch processing after primary goal ┃
|
|
246
|
+
┃ │ "Pursue the essential" ┃
|
|
247
|
+
┃ │ ┃
|
|
248
|
+
┃ ╰─────────────────────────── ↺ ──────────────────────────────────────┃
|
|
249
|
+
┃ ┃
|
|
250
|
+
┃ ┃
|
|
251
|
+
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
<br/>
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
<br/>
|
|
259
|
+
|
|
260
|
+
## ◈ Economic Model
|
|
261
|
+
|
|
262
|
+
<br/>
|
|
263
|
+
|
|
264
|
+
> *Intelligence has a cost. Ouroboros optimizes it.*
|
|
265
|
+
|
|
266
|
+
<br/>
|
|
267
|
+
|
|
268
|
+
| Tier | Cost | When | Philosophy |
|
|
269
|
+
|:----:|:----:|------|------------|
|
|
270
|
+
| `FRUGAL` | **1x** | complexity < 0.4 | *"Most problems are simpler than they appear"* |
|
|
271
|
+
| `STANDARD` | **10x** | complexity < 0.7 | *"Pay for quality when it matters"* |
|
|
272
|
+
| `FRONTIER` | **30x** | critical decisions | *"Some choices cannot be undone"* |
|
|
273
|
+
|
|
274
|
+
<br/>
|
|
275
|
+
|
|
276
|
+
```python
|
|
277
|
+
def select_approach(task):
|
|
278
|
+
if task.complexity < 0.4:
|
|
279
|
+
return Tier.FRUGAL # Start humble
|
|
280
|
+
|
|
281
|
+
if task.reversible:
|
|
282
|
+
return Tier.STANDARD # Move fast
|
|
283
|
+
|
|
284
|
+
if task.affects_direction:
|
|
285
|
+
return Tier.FRONTIER # Think deeply
|
|
286
|
+
|
|
287
|
+
return Tier.STANDARD
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
<br/>
|
|
291
|
+
|
|
292
|
+
**Result**: `~85% cost reduction` compared to "always use the best model"
|
|
293
|
+
|
|
294
|
+
<br/>
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
<br/>
|
|
299
|
+
|
|
300
|
+
## ◈ Architecture
|
|
301
|
+
|
|
302
|
+
<br/>
|
|
303
|
+
|
|
304
|
+
```
|
|
305
|
+
src/ouroboros/
|
|
306
|
+
│
|
|
307
|
+
├── core/ ◆ The essence: types, errors, seed, context
|
|
308
|
+
│
|
|
309
|
+
├── bigbang/ ◇ Phase 0: Interview → Ambiguity → Seed
|
|
310
|
+
│
|
|
311
|
+
├── routing/ ◇ Phase 1: PAL router, complexity, tiers
|
|
312
|
+
│
|
|
313
|
+
├── execution/ ◇ Phase 2: Double Diamond, decomposition
|
|
314
|
+
│
|
|
315
|
+
├── resilience/ ◇ Phase 3: Stagnation, lateral thinking
|
|
316
|
+
│
|
|
317
|
+
├── evaluation/ ◇ Phase 4: Mechanical, semantic, consensus
|
|
318
|
+
│
|
|
319
|
+
├── secondary/ ◇ Phase 5: TODO registry, batch scheduler
|
|
320
|
+
│
|
|
321
|
+
├── orchestrator/ ★ Claude Agent SDK integration
|
|
322
|
+
│
|
|
323
|
+
├── observability/ ○ Drift control, retrospective, logging
|
|
324
|
+
│
|
|
325
|
+
├── persistence/ ○ Event sourcing, checkpoints, recovery
|
|
326
|
+
│
|
|
327
|
+
├── providers/ ○ LiteLLM adapter (100+ models)
|
|
328
|
+
│
|
|
329
|
+
└── cli/ ○ Command-line interface
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
<br/>
|
|
333
|
+
|
|
334
|
+
---
|
|
335
|
+
|
|
336
|
+
<br/>
|
|
337
|
+
|
|
338
|
+
## ◈ The Personas (Lateral Thinking Agents)
|
|
339
|
+
|
|
340
|
+
<br/>
|
|
341
|
+
|
|
342
|
+
> *When stuck, the system doesn't retry harder. It switches persona and thinks differently.*
|
|
343
|
+
|
|
344
|
+
<br/>
|
|
345
|
+
|
|
346
|
+
| Persona | Strategy | Trigger | Behavior |
|
|
347
|
+
|:--------|:---------|:--------|:---------|
|
|
348
|
+
| **THE HACKER** | *"Elegance be damned. Make it work."* | Quick fix needed | Hardcode, skip abstractions, brute force |
|
|
349
|
+
| **THE RESEARCHER** | *"Stop coding. Read the docs."* | Knowledge gap detected | Search, read documentation, find examples |
|
|
350
|
+
| **THE SIMPLIFIER** | *"Cut scope in half. Return to MVP."* | Overengineering detected | Remove features, reduce complexity |
|
|
351
|
+
| **THE ARCHITECT** | *"Question the foundation. Rebuild if needed."* | Structural issues | Redesign, refactor core assumptions |
|
|
352
|
+
|
|
353
|
+
<br/>
|
|
354
|
+
|
|
355
|
+
**작동 방식**: Stagnation Detection (4 patterns) → Persona Rotation → 새로운 관점으로 재시도
|
|
356
|
+
|
|
357
|
+
<br/>
|
|
358
|
+
|
|
359
|
+
---
|
|
360
|
+
|
|
361
|
+
<br/>
|
|
362
|
+
|
|
363
|
+
## ◈ The Eternal Cycle
|
|
364
|
+
|
|
365
|
+
<br/>
|
|
366
|
+
|
|
367
|
+
```
|
|
368
|
+
┌─────────────────────────┐
|
|
369
|
+
│ │
|
|
370
|
+
▼ │
|
|
371
|
+
┌───────────────────┐ │
|
|
372
|
+
│ │ │
|
|
373
|
+
│ S E E D │ │
|
|
374
|
+
│ Ambiguity ≤ 0.2 │ │
|
|
375
|
+
│ │ │
|
|
376
|
+
└─────────┬─────────┘ │
|
|
377
|
+
│ │
|
|
378
|
+
▼ │
|
|
379
|
+
┌───────────────────┐ │
|
|
380
|
+
│ │ │
|
|
381
|
+
│ E X E C U T E │ │
|
|
382
|
+
│ PAL → Diamond │ │
|
|
383
|
+
│ │ │
|
|
384
|
+
└─────────┬─────────┘ │
|
|
385
|
+
│ │
|
|
386
|
+
▼ │
|
|
387
|
+
┌───────────────────┐ │
|
|
388
|
+
│ │ │
|
|
389
|
+
│ RETROSPECTIVE │ │
|
|
390
|
+
│ Every 3 cycles │ │
|
|
391
|
+
│ │ │
|
|
392
|
+
└─────────┬─────────┘ │
|
|
393
|
+
│ │
|
|
394
|
+
┌───────┴───────┐ │
|
|
395
|
+
▼ ▼ │
|
|
396
|
+
│
|
|
397
|
+
Drift OK Drift High │
|
|
398
|
+
│ │ │
|
|
399
|
+
▼ │ │
|
|
400
|
+
Continue ╰────────────────┘
|
|
401
|
+
Re-examine Seed
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
<br/>
|
|
405
|
+
|
|
406
|
+
The system doesn't blindly loop.
|
|
407
|
+
It **questions its own direction**.
|
|
408
|
+
|
|
409
|
+
When drift exceeds threshold, it returns to the beginning—
|
|
410
|
+
not to restart, but to **re-crystallize** with new understanding.
|
|
411
|
+
|
|
412
|
+
<br/>
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
<br/>
|
|
417
|
+
|
|
418
|
+
## ◈ Quick Start
|
|
419
|
+
|
|
420
|
+
<br/>
|
|
421
|
+
|
|
422
|
+
### Using Claude Code Max Plan (Recommended)
|
|
423
|
+
|
|
424
|
+
No API key required — uses your Claude Code subscription directly.
|
|
425
|
+
|
|
426
|
+
```bash
|
|
427
|
+
# Clone
|
|
428
|
+
git clone https://github.com/Q00/ouroboros
|
|
429
|
+
cd ouroboros
|
|
430
|
+
|
|
431
|
+
# Install
|
|
432
|
+
uv sync
|
|
433
|
+
|
|
434
|
+
# Begin the Big Bang (interactive interview)
|
|
435
|
+
uv run ouroboros init start --orchestrator "I want to build a task management CLI"
|
|
436
|
+
|
|
437
|
+
# Execute via Claude Agent SDK
|
|
438
|
+
uv run ouroboros run workflow --orchestrator seed.yaml
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
### Using External LLM (LiteLLM)
|
|
442
|
+
|
|
443
|
+
Requires API key (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, etc.)
|
|
444
|
+
|
|
445
|
+
```bash
|
|
446
|
+
# Begin the Big Bang
|
|
447
|
+
uv run ouroboros init start "I want to build a task management CLI"
|
|
448
|
+
|
|
449
|
+
# Check status
|
|
450
|
+
uv run ouroboros status health
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)**
|
|
454
|
+
|
|
455
|
+
<br/>
|
|
456
|
+
|
|
457
|
+
---
|
|
458
|
+
|
|
459
|
+
<br/>
|
|
460
|
+
|
|
461
|
+
## ◈ Anti-Patterns
|
|
462
|
+
|
|
463
|
+
<br/>
|
|
464
|
+
|
|
465
|
+
> *What we explicitly reject:*
|
|
466
|
+
|
|
467
|
+
<br/>
|
|
468
|
+
|
|
469
|
+
| ✗ Anti-Pattern | Problem | ✓ Our Solution |
|
|
470
|
+
|----------------|---------|----------------|
|
|
471
|
+
| Consensus Everywhere | Cost explosion | Gate-only consensus |
|
|
472
|
+
| Frontier First | Wasteful | Frugal first, escalate |
|
|
473
|
+
| Infinite Retry | Stagnation | Lateral thinking |
|
|
474
|
+
| Immediate Optimization | Yak shaving | TODO registry (defer) |
|
|
475
|
+
| Vague Seeds | GIGO | Ambiguity ≤ 0.2 |
|
|
476
|
+
|
|
477
|
+
<br/>
|
|
478
|
+
|
|
479
|
+
---
|
|
480
|
+
|
|
481
|
+
<br/>
|
|
482
|
+
|
|
483
|
+
## ◈ Development
|
|
484
|
+
|
|
485
|
+
<br/>
|
|
486
|
+
|
|
487
|
+
```bash
|
|
488
|
+
# Install all dependencies
|
|
489
|
+
uv sync --all-groups
|
|
490
|
+
|
|
491
|
+
# Run tests
|
|
492
|
+
uv run pytest
|
|
493
|
+
|
|
494
|
+
# Type checking
|
|
495
|
+
uv run mypy src/
|
|
496
|
+
|
|
497
|
+
# Lint
|
|
498
|
+
uv run ruff check src/
|
|
499
|
+
|
|
500
|
+
# Format
|
|
501
|
+
uv run ruff format src/
|
|
502
|
+
```
|
|
503
|
+
|
|
504
|
+
<br/>
|
|
505
|
+
|
|
506
|
+
---
|
|
507
|
+
|
|
508
|
+
<br/>
|
|
509
|
+
|
|
510
|
+
## ◈ Roadmap
|
|
511
|
+
|
|
512
|
+
<br/>
|
|
513
|
+
|
|
514
|
+
```
|
|
515
|
+
[■■■■■■■■■■] Epic 0 Foundation
|
|
516
|
+
[■■■■■■■■■■] Epic 1 Big Bang
|
|
517
|
+
[■■■■■■■■■■] Epic 2 PAL Router
|
|
518
|
+
[■■■■■■■■■■] Epic 3 Double Diamond
|
|
519
|
+
[■■■■■■■■■■] Epic 4 Resilience
|
|
520
|
+
[■■■■■■■■■■] Epic 5 Evaluation
|
|
521
|
+
[■■■■■■■■■■] Epic 6 Drift Control
|
|
522
|
+
[■■■■■■■■■■] Epic 7 Secondary Loop
|
|
523
|
+
[■■■■■■■■■■] Epic 8 Orchestrator ✓ Complete
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
<br/>
|
|
527
|
+
|
|
528
|
+
---
|
|
529
|
+
|
|
530
|
+
<br/>
|
|
531
|
+
|
|
532
|
+
## ◈ Why "Ouroboros"?
|
|
533
|
+
|
|
534
|
+
<br/>
|
|
535
|
+
|
|
536
|
+
<table>
|
|
537
|
+
<tr>
|
|
538
|
+
<td width="100%">
|
|
539
|
+
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
╭──────────╮
|
|
543
|
+
╭───╯ ╰───╮
|
|
544
|
+
╭─╯ ╰─╮
|
|
545
|
+
╭╯ ◯ ← ◯ ╰╮
|
|
546
|
+
│ ↗ ↘ │
|
|
547
|
+
│ ◯ ⚬ ◯ │
|
|
548
|
+
│ ↖ ↙ │
|
|
549
|
+
╰╮ ◯ → ◯ ╭╯
|
|
550
|
+
╰─╮ ╭─╯
|
|
551
|
+
╰───╮ ╭───╯
|
|
552
|
+
╰──────────╯
|
|
553
|
+
|
|
554
|
+
The serpent that devours itself to be reborn.
|
|
555
|
+
|
|
556
|
+
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
</td>
|
|
560
|
+
</tr>
|
|
561
|
+
</table>
|
|
562
|
+
|
|
563
|
+
<br/>
|
|
564
|
+
|
|
565
|
+
The ouroboros has symbolized eternal cycles of renewal for millennia.
|
|
566
|
+
|
|
567
|
+
Software development is no different:
|
|
568
|
+
|
|
569
|
+
```
|
|
570
|
+
Write → Test → Fail → Learn → Rewrite → Test → ...
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
The question is not *whether* to iterate, but *how to iterate wisely*.
|
|
574
|
+
|
|
575
|
+
<br/>
|
|
576
|
+
|
|
577
|
+
**Ouroboros answers:**
|
|
578
|
+
|
|
579
|
+
1. **Start with truth** — Socratic questioning extracts essence
|
|
580
|
+
2. **Be frugal in execution** — Don't waste intelligence on simple problems
|
|
581
|
+
3. **Be rigorous in verification** — Critical decisions need consensus
|
|
582
|
+
4. **Trust the cycle** — Let the serpent eat its tail and be reborn
|
|
583
|
+
|
|
584
|
+
<br/>
|
|
585
|
+
|
|
586
|
+
---
|
|
587
|
+
|
|
588
|
+
<br/>
|
|
589
|
+
|
|
590
|
+
<p align="center">
|
|
591
|
+
<br/>
|
|
592
|
+
<br/>
|
|
593
|
+
<em>"The beginning is the end, and the end is the beginning."</em>
|
|
594
|
+
<br/>
|
|
595
|
+
<br/>
|
|
596
|
+
<br/>
|
|
597
|
+
</p>
|
|
598
|
+
|
|
599
|
+
---
|
|
600
|
+
|
|
601
|
+
<br/>
|
|
602
|
+
|
|
603
|
+
<p align="center">
|
|
604
|
+
<code>MIT License</code>
|
|
605
|
+
</p>
|
|
606
|
+
|
|
607
|
+
<br/>
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
ouroboros/__init__.py,sha256=OGnic_GtjWWUQ3JWfyhX0SftJL0iwCH8ezD-FM7i-b4,304
|
|
2
|
+
ouroboros/__main__.py,sha256=f_qnL0zPJwh9kfQqynX5adpqzj8ilj94zW5Q2loqGxE,168
|
|
3
|
+
ouroboros/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
4
|
+
ouroboros/bigbang/__init__.py,sha256=9xGqOYwMKBifb7QVwonc_wndNLMZb7ZH7xgMHaz_70A,951
|
|
5
|
+
ouroboros/bigbang/ambiguity.py,sha256=KRHBSNmAB2zTI0ZD4zuP_mGWXr3jXdPuFgE57wsMg8Y,15619
|
|
6
|
+
ouroboros/bigbang/interview.py,sha256=4TFRnD9KSH5oVZ8Mxgc6ea2YT2CQSVzjFnm1lSPHtZM,16890
|
|
7
|
+
ouroboros/bigbang/seed_generator.py,sha256=7MY9a7Eua_zVGDWIVDlzOZJjeAwz0DRatXJg0PvMgiY,20082
|
|
8
|
+
ouroboros/cli/__init__.py,sha256=CRpxsqJadZL7bCS-yrULWC51tqPKfPsxQLgt0JiwP4g,225
|
|
9
|
+
ouroboros/cli/main.py,sha256=ldvqtVpw2xZwE8G7M34qY_7qg0RuNiydjdmmU-hdJvM,1485
|
|
10
|
+
ouroboros/cli/commands/__init__.py,sha256=LZpEvU80R4Cq0LwgkwOluEGNsmmJ9K7roeDQ6bsbbDc,193
|
|
11
|
+
ouroboros/cli/commands/config.py,sha256=kcqi0Wo09oo1MMyZIX4k2IDICV1SAX6HzAXZaIJGdKY,2100
|
|
12
|
+
ouroboros/cli/commands/init.py,sha256=HmXwTLyso6p8Df5aAguxh-XTIYZGkzGltGXqJvDxI78,13536
|
|
13
|
+
ouroboros/cli/commands/run.py,sha256=pcjt5UIlNjOHM5_O8G0MLDOUqCRg0Cv2IKNIK_gS5gg,5973
|
|
14
|
+
ouroboros/cli/commands/status.py,sha256=Bnqpj1UkqhpBPYA11DV-Z63Bz8pjrebhlzeMKwz3_Ps,2217
|
|
15
|
+
ouroboros/cli/formatters/__init__.py,sha256=-Ik7KXajaIExBxSAp5iYp8gO9SfXudGjyDe2nm2_msw,691
|
|
16
|
+
ouroboros/cli/formatters/panels.py,sha256=d5TANIZy6FEEdpfnZaZ0epe-qIHJbh13qTCt23ur1jA,3388
|
|
17
|
+
ouroboros/cli/formatters/progress.py,sha256=OLGpZteuGOyDXvDc0AD4UJcjYstUnSEertvywH60bHo,3288
|
|
18
|
+
ouroboros/cli/formatters/tables.py,sha256=XDzeew8d7_b-cQ54QH16fljR-lmwwo94-9GbprQa8OY,4487
|
|
19
|
+
ouroboros/config/__init__.py,sha256=rQv4ph9qv1jP6YmIOOFBM-pjDR5br9RcW693mr0Hj_U,2006
|
|
20
|
+
ouroboros/config/loader.py,sha256=yqHdrQs3bHbpp49jbjctRDx-zfFNI2rLco8JX44Awr0,8907
|
|
21
|
+
ouroboros/config/models.py,sha256=d12m7-pCTQQASFfBTShIRS0zStn1gpzRWYe68Aky9T0,11740
|
|
22
|
+
ouroboros/core/__init__.py,sha256=BbRkisCNTaM6eCrh2yppKhaQqAf2ZAy7tQH3Qmv5vSE,1363
|
|
23
|
+
ouroboros/core/ac_tree.py,sha256=GNyeWB3GVrQhYI83_g2ISYoviKnUf-U6vTY9p6xkklM,11949
|
|
24
|
+
ouroboros/core/context.py,sha256=A5WVPgsJlK-CDnDJx-_Tcfh_lE2AE3EYud45NKnYI2E,15675
|
|
25
|
+
ouroboros/core/errors.py,sha256=e4kiduueE3e2HvNyOJLnFRGFoue2vfW8JTerzxjp5TM,8057
|
|
26
|
+
ouroboros/core/seed.py,sha256=OIO4p1evYqpIrt841LVDVMaBZq9RCkM-e78MOb94BS8,7114
|
|
27
|
+
ouroboros/core/types.py,sha256=SIc7XSIRizkeQU0kq4U02mZFsLtqVLmAo3ANypyUUfQ,6137
|
|
28
|
+
ouroboros/evaluation/__init__.py,sha256=rwNeCtbFvDmq2Ad3YXj2n1tz2i9fESHQKwgjIyCZtCs,3067
|
|
29
|
+
ouroboros/evaluation/consensus.py,sha256=iPa21cdLHWBBBuFaHDxI638UH3n-XFmp5TZrrxJ23k0,10727
|
|
30
|
+
ouroboros/evaluation/mechanical.py,sha256=gWvCUaR8Ibmpnrl9gjv0LYhwC5MgJ65gyTFcjzHqLZc,11285
|
|
31
|
+
ouroboros/evaluation/models.py,sha256=SpUOhchp2G0zzsXiNiIZ8txJhxK1vcgPxS1_4tWvZUY,7538
|
|
32
|
+
ouroboros/evaluation/pipeline.py,sha256=k4gQzkKxzMvqKpMxK4bAVAm-Ux06RYjlwNOCDD5EvQI,10056
|
|
33
|
+
ouroboros/evaluation/semantic.py,sha256=qSKrYHMzt8DLygULH5xI2Sy_pXfis9-_bIjjziUf3kI,9406
|
|
34
|
+
ouroboros/evaluation/trigger.py,sha256=yNQZrVAP8L6KOKNDQNqeCxDqxbYIZY8b7w-lBSMlL5A,9695
|
|
35
|
+
ouroboros/events/__init__.py,sha256=LIvrE41r1eGo6Qb1-mOfoyVAcZ3hObS4o7Jq3sCnVPU,140
|
|
36
|
+
ouroboros/events/base.py,sha256=y4ZIqs_HK66GRVZz7HZ02pkQ8lS2NxIkJFOB3frm8y0,2627
|
|
37
|
+
ouroboros/events/decomposition.py,sha256=rA2E4SLB5UgEZMXzGPFVO75r1D96PWQ8PnBBJKug3nE,4357
|
|
38
|
+
ouroboros/events/evaluation.py,sha256=HfQ6xu5JLV5tIjL-NxsXykDIvKmjBSrLr1tQHcr4aAI,6922
|
|
39
|
+
ouroboros/execution/__init__.py,sha256=nG9f51vi1O3zLGusbZfOqZebvUgMxm9R7JjoUDPGC1E,1101
|
|
40
|
+
ouroboros/execution/atomicity.py,sha256=JacsYaUhm9r05R8sMBoJRDnTmba4jpMXQU6SvQIuAzM,13988
|
|
41
|
+
ouroboros/execution/decomposition.py,sha256=NWTVuQoLw4vzMMGNdtCv-i5olOGIZADd2ogdFURzssU,14682
|
|
42
|
+
ouroboros/execution/double_diamond.py,sha256=lbk9cY3Awd0h_YFp1G5OJnDpkV8htanSDhQIYn0LA_8,49837
|
|
43
|
+
ouroboros/execution/subagent.py,sha256=_0-Ayz1p4r-cJP6kAYQP-bf9g2yLKXV81wffurBK9YM,8727
|
|
44
|
+
ouroboros/observability/__init__.py,sha256=jgLIxPgBPJgSLCUjxR28tO3gkOuknbnb0H87NwkCl6Q,1654
|
|
45
|
+
ouroboros/observability/drift.py,sha256=1BxZq-XIfhOJpTiBzbqgMpxziiJsb9KcLg_F5QKBIeM,11361
|
|
46
|
+
ouroboros/observability/logging.py,sha256=LrGe8lrJp2D-kNXCToMPp_sU2Dhh_rxMGf7_2O4sDpQ,14908
|
|
47
|
+
ouroboros/observability/retrospective.py,sha256=FH_9UC20RnH7OHNXMVIbsqC74B_4KIUy0UjtK-rguXU,11177
|
|
48
|
+
ouroboros/orchestrator/__init__.py,sha256=g1aZSEM9gbl12mHINYoS93X1gacqePwrK4ElujoN0Uk,2130
|
|
49
|
+
ouroboros/orchestrator/adapter.py,sha256=TpvgVMNfvNqvuffn41JDMYjWt2MFCLqTW1MtwOEZ-6E,13152
|
|
50
|
+
ouroboros/orchestrator/events.py,sha256=Ti83WTW9sGNJtR-KKcJ_Ie62oEqggIoivgfzIl19Ydg,7604
|
|
51
|
+
ouroboros/orchestrator/runner.py,sha256=AbD8vAyUlXQk8KUpmizkm_i4YM03XeqaE-15ElxwsnA,20386
|
|
52
|
+
ouroboros/orchestrator/session.py,sha256=JWfQfwwlf7_f80l9Ed45zQA6iDb32XoOnaYbGjA6ChU,15536
|
|
53
|
+
ouroboros/persistence/__init__.py,sha256=O9lVtKUNgtpamzo-OAeEVYXByqpy83853DKepvo3Zj8,601
|
|
54
|
+
ouroboros/persistence/checkpoint.py,sha256=FC68lOmNcRJooFEYXGrGWR0TZcQG-YA9qvPPnl4QMUc,17580
|
|
55
|
+
ouroboros/persistence/event_store.py,sha256=XWGZaJRPGbYMyTuE98dOZhU07nQ_ZeWkxxUhnVgMKd4,6229
|
|
56
|
+
ouroboros/persistence/schema.py,sha256=eS5IcSEnnna7CIhS5Whx1iURC8_DV3xu69Vr_bV_N-Y,1796
|
|
57
|
+
ouroboros/persistence/uow.py,sha256=suAKSrbZrofl2KNsHCfbQZ8K1bnJJW956lTkKkhwkdQ,7461
|
|
58
|
+
ouroboros/persistence/migrations/__init__.py,sha256=H3MwTYP02lLnUpCUTNf-B9ONS15thPPgB-T6x2heetc,34
|
|
59
|
+
ouroboros/persistence/migrations/runner.py,sha256=FPlnmjT0U-wTDRdHHImM6wMzEzMAGXlcirTwkUQRWVw,2997
|
|
60
|
+
ouroboros/persistence/migrations/scripts/001_initial.sql,sha256=ZkABj9VKEyvwYwCmnT7PZt8bODMKUw4oThnuhHdxHwg,848
|
|
61
|
+
ouroboros/providers/__init__.py,sha256=sFQ049Gizx2GxWUTlsCLZHaskV8NVwPDdkXiLEWhrbc,583
|
|
62
|
+
ouroboros/providers/base.py,sha256=u86bWAXtNIVCL1SxqXFK9sqpL6SZOc9h2vxAuVh7mxo,3823
|
|
63
|
+
ouroboros/providers/claude_code_adapter.py,sha256=rVz_5eYRPL9SMt5PQBIbYGHLkRymTCXjCwZ6oZwMrCM,7285
|
|
64
|
+
ouroboros/providers/litellm_adapter.py,sha256=OcCeph2ItQXup8MHNkDB_5EQGb3P-wtzT4T3jHAydnY,10160
|
|
65
|
+
ouroboros/resilience/__init__.py,sha256=jcMdyk5WwaIh7iFVQ5rwaexCnnVpnumJUgWf4GO6w_4,1980
|
|
66
|
+
ouroboros/resilience/lateral.py,sha256=Z4B7pOrD93D6bXu8BqrUvibqYSGyjv8Ubp6nWfLipjM,21582
|
|
67
|
+
ouroboros/resilience/stagnation.py,sha256=k9tiAm__CzclpfRB6Z-8jZdfRwvr2la-BsqDJmEq8Ao,25659
|
|
68
|
+
ouroboros/routing/__init__.py,sha256=DUdFtcGfFRLRuGDWZ9oIk02-4vYAgYPt5XQRGfBUzF0,1520
|
|
69
|
+
ouroboros/routing/complexity.py,sha256=kxF8KVgI8Fpb6gKZxBCdWGuLhWLsUKwGyhDgMhN-gtI,8477
|
|
70
|
+
ouroboros/routing/downgrade.py,sha256=XaelFGLBM1qCyi_E0rekAQ7iYi6o857BErPztloTuHo,21763
|
|
71
|
+
ouroboros/routing/escalation.py,sha256=8mOlyFeByoQmsW13X4rzeg-uEaTRlLAPhuRYfSbai5w,11051
|
|
72
|
+
ouroboros/routing/router.py,sha256=7rr98rbFYJWL6jGaSdvR1H-hRf-keaK1ul-JFvljLXc,6663
|
|
73
|
+
ouroboros/routing/tiers.py,sha256=QhBQUOo2-h5Z3dEtC0lcOzkRnqTi2W7Jl46750AVNig,7307
|
|
74
|
+
ouroboros/secondary/__init__.py,sha256=kYQ7C4bnBzwDlPrU8qZrOPr2ZuTBaftGktOXl5WZl5Q,1123
|
|
75
|
+
ouroboros/secondary/scheduler.py,sha256=sPVVWJ1q0yewRAM-Rm1j_HMerSe4cavIvP9z4xlUuL4,13737
|
|
76
|
+
ouroboros/secondary/todo_registry.py,sha256=4W3C9Uro29VrVLCPKUlpH_BYpzQSbRNW1oMnDYyEhEw,13880
|
|
77
|
+
ouroboros_ai-0.1.0.dist-info/METADATA,sha256=Lbte26MnJOkEOYSa-0oc54S_ZuurG4DN-xeS45a2pN4,18504
|
|
78
|
+
ouroboros_ai-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
79
|
+
ouroboros_ai-0.1.0.dist-info/entry_points.txt,sha256=MoETHup6rVkR6AsyjoRzAgIuvVtYYm3Jw40itV3_VyI,53
|
|
80
|
+
ouroboros_ai-0.1.0.dist-info/licenses/LICENSE,sha256=n2X-q26TqpXnoBo0t_WouhFxWw663_q5FmbYDZayoHo,1060
|
|
81
|
+
ouroboros_ai-0.1.0.dist-info/RECORD,,
|