SYNTAX.md
1 # DreamTalk Canonical Syntax 2 3 *The platonic specification for DreamWeavings.* 4 5 --- 6 7 ## The Greater Trinity 8 9 DreamTalk exists within a larger metaphysical framework: 10 11 | Aspect | Domain | What it IS | 12 |--------|--------|------------| 13 | **DreamTalk** | Kairos (timeless) | Sovereign symbols - holons as relational patterns | 14 | **DreamSong** | Kronos (temporal) | Scenes/videos - holons expressing through time | 15 | **DreamWeaving** | Intersection | The Python file - bridging timeless pattern and temporal expression | 16 17 A **DreamTalk symbol** is a timeless relational structure (the class definition). 18 A **DreamSong** is a chronological sequence where symbols express themselves (the `unfold()` method). 19 A **DreamWeaving** is the act of creation itself - the living Python file that contains both. 20 21 The creative flow: You tell a story (DreamSong) using symbols (DreamTalk), and as you do, 22 a higher-level holon crystallizes (the file becomes a new DreamTalk symbol). 23 24 --- 25 26 ## The Syntax Trinity 27 28 DreamTalk encodes a metaphysical framework into its syntax: 29 30 | Concept | Domain | DreamTalk | Manifestation | 31 |---------|--------|-----------|---------------| 32 | **Kairos** | Timeless pattern | **Holon** | The class definition | 33 | **Kronos** | Temporal flow | **Dream** | The `unfold()` method | 34 | **Intersection** | Living bridge | **DreamWeaving** | The Python file itself | 35 36 - **Kairos**: The eternal now. Relationships exist outside time. 37 - **Kronos**: Sequential time. Events unfold in order. 38 - **DreamWeaving**: The act of pulling Kairos into Kronos. 39 40 ### The Observer 41 42 The **Observer** is the consciousness perceiving the dream. There is no fundamental 43 distinction between 2D and 3D - just different configurations of observation. 44 45 ```python 46 class MyDream(Dream): 47 def unfold(self): 48 # 2D-style work (subset of 3D) 49 self.observer.pan(x=100, y=50) 50 self.observer.zoom(factor=0.5) 51 52 # 3D-style work 53 self.observer.orbit(phi=PI/4, theta=PI/6) 54 self.observer.dolly(radius=1500) 55 ``` 56 57 A "2D scene" is simply an Observer looking straight at the XY plane. 58 A "3D scene" uses the same Observer with orbital controls. 59 60 --- 61 62 ## File Structure 63 64 Every DreamWeaving follows this pattern: 65 66 ```python 67 """ 68 <HolonName>.py - A DreamWeaving 69 70 <Description of what this holon represents.> 71 """ 72 73 from dreamtalk import Holon, Dream 74 from dreamtalk.types import Length, Angle, Bipolar, Color, Completion 75 from dreamtalk.parts import Circle, Sphere, FoldableCube # etc. 76 from dreamtalk.animation import Create, Draw, Morph 77 78 # === Kairos: The Timeless Pattern === 79 80 class <HolonName>(Holon): 81 """<What this holon IS - its essential nature.>""" 82 83 # Parameters - degrees of freedom 84 <param>: <Type> = <default> 85 86 def specify_parts(self): 87 """Define parts and their relationships to this whole.""" 88 self.<part> = <PartClass>( 89 <property> << self.<param>, # one-way binding 90 <property> <> self.<param>, # bidirectional constraint 91 ) 92 self.parts = [self.<part>, ...] 93 94 95 # === Kronos: The Temporal Unfolding === 96 97 if __name__ == "__main__": 98 99 class <HolonName>Dream(Dream): 100 """<What happens when this holon dreams itself into existence.>""" 101 102 def unfold(self): 103 <holon> = <HolonName>(<params>) 104 self.play(Create(<holon>), run_time=1.5) 105 # ... temporal sequence ... 106 107 <HolonName>Dream() 108 ``` 109 110 --- 111 112 ## Parameter Types 113 114 Parameters define the degrees of freedom of a holon: 115 116 | Type | Range | Example | 117 |------|-------|---------| 118 | `Length` | 0 → ∞ | `radius: Length = 100` | 119 | `Angle` | 0 → 2π | `rotation: Angle = 0` | 120 | `Bipolar` | -1 → 1 | `fold: Bipolar = 0` | 121 | `Completion` | 0 → 1 | `progress: Completion = 0` | 122 | `Color` | RGB/named | `color: Color = BLUE` | 123 | `Integer` | ℤ | `count: Integer = 6` | 124 125 These are **semantic types** - they communicate intent and enable smart defaults in the UI. 126 127 --- 128 129 ## Binding Operators 130 131 ### `<<` One-Way Binding (Whole → Part) 132 133 The part's property follows the whole's parameter: 134 135 ```python 136 self.circle = Circle( 137 radius << self.size # circle.radius follows self.size 138 ) 139 ``` 140 141 Data flows **downward** through the holarchy. The part receives from the whole. 142 143 ### `<>` Bidirectional Constraint 144 145 Mutual relationship - neither dominates: 146 147 ```python 148 self.a = Circle(radius <> self.b.radius) # they stay equal 149 ``` 150 151 Use sparingly. Most relationships are hierarchical (`<<`). 152 153 --- 154 155 ## Behaviors 156 157 Behaviors are methods that return animations - ways of moving through Kronos: 158 159 ```python 160 class MindVirus(Holon): 161 fold: Bipolar = 0 162 163 def specify_parts(self): 164 self.cube = FoldableCube(fold << self.fold) 165 self.parts = [self.cube] 166 167 # Behaviors 168 def thrust_pulse(self, distance=100): 169 """Jellyfish-like locomotion.""" 170 return AnimationGroup( 171 self.animate.fold.sequence(1, 0.1, 1), 172 self.animate.z(-distance) 173 ) 174 175 def hunt(self, target): 176 """Move toward a target.""" 177 return self.animate.position(target.position) 178 ``` 179 180 Usage in a Dream: 181 182 ```python 183 def unfold(self): 184 virus = MindVirus() 185 self.play(virus.thrust_pulse(200), run_time=1.2) 186 ``` 187 188 --- 189 190 ## The `.animate` Pattern 191 192 Fluent animation syntax (inspired by Manim): 193 194 ```python 195 # Animate a single parameter 196 self.play(virus.animate.fold(0.5), run_time=1) 197 198 # Chain multiple animations 199 self.play( 200 virus.animate.fold(0.5).color(RED).scale(2), 201 run_time=1.5 202 ) 203 204 # Sequence of values 205 self.play(virus.animate.fold.sequence(1, 0.1, 1), run_time=2) 206 ``` 207 208 --- 209 210 ## State Machines 211 212 For agentic holons with discrete modes: 213 214 ```python 215 class MindVirus(Holon): 216 fold: Bipolar = 0 217 218 class States: 219 idle = State(fold=1) 220 hunting = State(fold=0.5) 221 attached = State(fold=-1) 222 223 def specify_parts(self): 224 # ... 225 ``` 226 227 Transition between states: 228 229 ```python 230 def unfold(self): 231 virus = MindVirus() 232 self.play(virus.transition_to(virus.States.hunting), run_time=0.5) 233 ``` 234 235 --- 236 237 ## Fields (Spatial Relationships) 238 239 For MoGraph-like spatial distributions: 240 241 ```python 242 class Swarm(Holon): 243 attraction: Length = 100 244 245 def specify_parts(self): 246 self.field = AttractionField(strength=self.attraction) 247 self.viruses = [MindVirus() for _ in range(10)] 248 249 for virus in self.viruses: 250 virus.velocity << self.field.at(virus.position) 251 252 self.parts = [self.field, *self.viruses] 253 ``` 254 255 --- 256 257 ## Temporal Bindings 258 259 For time-entangled relationships: 260 261 ```python 262 # Delayed binding - b follows a with 0.5s delay 263 self.b.position << self.a.position.delayed(0.5) 264 265 # Creates trailing/following effects 266 ``` 267 268 --- 269 270 ## Morphing (Transform) 271 272 Morphing is a **capability** of spline-based holons, not a separate class. 273 274 ```python 275 # Morph one shape into another 276 self.play(word.morph_to(logo), run_time=2) 277 278 # Or using Transform (Manim-style naming) 279 self.play(Transform(word, logo), run_time=2) 280 ``` 281 282 The morph handles: 283 - Spline interpolation between source and target 284 - Automatic visibility handoff at midpoint 285 - Stroke completion animation during transition 286 287 **Design principle**: Abilities belong to objects, not to separate "stuntman" classes. 288 If a LineObject can draw itself, it can also morph itself. 289 290 --- 291 292 ## Complete Example 293 294 ```python 295 """ 296 MindVirus.py - A DreamWeaving 297 298 A manipulative narrative with folding control mechanism. 299 The eye sees; the cube entraps. 300 """ 301 302 from dreamtalk import Holon, Dream 303 from dreamtalk.types import Bipolar, Color, Length 304 from dreamtalk.parts import Circle, FoldableCube 305 from dreamtalk.animation import Create, AnimationGroup 306 307 # === Kairos: The Timeless Pattern === 308 309 class MindVirus(Holon): 310 """A self-replicating thought-form that attaches to minds.""" 311 312 # Parameters 313 fold: Bipolar = 0 # -1 (wrapped) to 1 (open) 314 color: Color = BLUE 315 size: Length = 100 316 317 # States 318 class States: 319 idle = State(fold=1) 320 hunting = State(fold=0.5) 321 attached = State(fold=-1) 322 323 def specify_parts(self): 324 self.eye = Circle( 325 radius << self.size * 0.2 326 ) 327 self.cube = FoldableCube( 328 fold << self.fold, 329 color << self.color, 330 size << self.size 331 ) 332 self.parts = [self.eye, self.cube] 333 334 # Behaviors 335 def thrust_pulse(self, distance=100): 336 """Jellyfish-like locomotion through the void.""" 337 return AnimationGroup( 338 self.animate.fold.sequence(1, 0.1, 1), 339 self.animate.z(-distance) 340 ) 341 342 343 # === Kronos: The Temporal Unfolding === 344 345 if __name__ == "__main__": 346 347 class MindVirusDream(Dream): 348 """A MindVirus awakens, pulses, and hunts.""" 349 350 def unfold(self): 351 virus = MindVirus(color=PURPLE, size=150) 352 353 # Emerge from nothing 354 self.play(Create(virus), run_time=1.5) 355 356 # Pulse through space 357 self.play(virus.thrust_pulse(200), run_time=1.2) 358 self.play(virus.thrust_pulse(150), run_time=1.0) 359 360 # Settle into hunting stance 361 self.play( 362 virus.transition_to(virus.States.hunting), 363 run_time=0.8 364 ) 365 366 self.wait(1) 367 368 MindVirusDream() 369 ``` 370 371 --- 372 373 ## Naming Conventions 374 375 | Element | Convention | Example | 376 |---------|------------|---------| 377 | Holon class | PascalCase | `MindVirus`, `FlowerOfLife` | 378 | Dream class | `<Holon>Dream` | `MindVirusDream` | 379 | Parameters | snake_case | `fold`, `inner_radius` | 380 | Parts | snake_case | `self.eye`, `self.cube` | 381 | Behaviors | snake_case verb | `thrust_pulse`, `hunt` | 382 | States | snake_case | `States.idle`, `States.hunting` | 383 | File | `<Holon>.py` | `MindVirus.py` | 384 385 --- 386 387 ## Philosophy Encoded 388 389 The syntax itself teaches: 390 391 1. **Holon** - Every whole is also a part. Sovereignty at every scale. 392 393 2. **`<<` flows downward** - The whole provides for its parts. Masculine serves feminine. 394 395 3. **`unfold()` not `construct()`** - We don't build; we allow revelation. 396 397 4. **Dream not Scene** - Creation is dreaming, not engineering. 398 399 5. **The file IS the holon** - Code and manifestation are one. The map is the territory. 400 401 6. **Kairos contains Kronos** - The timeless class definition contains all possible temporal unfoldings. 402 403 --- 404 405 *DreamTalk: Where mathematics dreams itself into motion.*