Commit ba9e2bf

@@ -30,6 +30,100 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+REPL State Diagram
+
+```
+                      ┌─────────────────┐
+                      │   START/INIT    │
+                      └─────────┬───────┘
+                                │
+                                v
+                      ┌─────────────────┐
+                ┌────▶│ IDLE (Prompt)   │◄────┐
+                │     │   Shows "> "    │     │
+                │     └─────────┬───────┘     │
+                │               │             │
+                │               │ User input  │
+                │               v             │
+                │     ┌─────────────────┐     │
+                │     │ PROCESSING      │     │
+                │     │ INPUT           │     │
+                │     └─────────┬───────┘     │
+                │               │             │
+                │               │ API call    │
+                │               v             │
+                │     ┌─────────────────┐     │
+                │     │ STREAMING       │     │
+                │ ┌──▶│ RESPONSE        │─────┤
+                │ │   └─────────┬───────┘     │
+                │ │             │             │ done=true
+                │ │             │ Parse chunk │
+                │ │             v             │
+                │ │   ┌─────────────────┐     │
+                │ │   │ MESSAGE TYPE    │     │
+                │ │   │ ROUTING         │     │
+                │ │   └─────┬─┬─┬───────┘     │
+                │ │         │ │ │             │
+       ┌────────┴─┴─────────┘ │ └─────────────┴──────────┐
+       │                      │                          │
+       v                      v                          v
+  ┌─────────────┐    ┌─────────────┐          ┌─────────────┐
+  │ THINKING    │    │ TOOL        │          │ CONTENT     │
+  │ STATE       │    │ EXECUTION   │          │ OUTPUT      │
+  │             │    │ STATE       │          │ STATE       │
+  └─────────────┘    └─────┬───────┘          └─────────────┘
+       │                   │                          │
+       │                   │ done=false               │
+       └───────────────────┼──────────────────────────┘
+                           │
+                           v
+                 ┌─────────────────┐
+                 │ CONTINUE        │
+                 │ STREAMING       │
+                 └─────────────────┘
+                           │
+                           └─────────────────┐
+                                             │
+       ┌─────────────────┐                   │
+       │ ERROR STATE     │                   │
+       │ (Exception)     │                   │
+       └─────────────────┘                   │
+                ▲                            │
+                │ Invalid response           │
+                └────────────────────────────┘
+
+                      EXIT CONDITIONS:
+                 ┌─────────────────────────┐
+                 │ • User enters ""        │
+                 │ • User enters "exit"    │
+                 │ • EOF (Ctrl+D)          │
+                 │ • nil input             │
+                 └─────────────────────────┘
+                            │
+                            v
+                 ┌─────────────────────────┐
+                 │      TERMINATE          │
+                 └─────────────────────────┘
+```
+
+Key Transitions:
+
+1. IDLE → PROCESSING: User enters any non-empty, non-"exit" input
+2. PROCESSING → STREAMING: API call initiated to Ollama
+3. STREAMING → MESSAGE ROUTING: Each chunk received is parsed
+4. MESSAGE ROUTING → States: Based on message content:
+  - thinking → THINKING STATE
+  - tool_calls → TOOL EXECUTION STATE
+  - content → CONTENT OUTPUT STATE
+  - Invalid format → ERROR STATE
+5. All States → IDLE: When done=true from API response
+6. TOOL EXECUTION → STREAMING: Sets done=false to continue conversation
+7. Any State → TERMINATE: On exit conditions
+
+The REPL operates as a continuous loop where the primary flow is IDLE → PROCESSING → STREAMING →
+back to IDLE, with the streaming phase potentially cycling through multiple message types before
+completion.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/xlgmokha/elelem.