git push origin fix-mermaid-architecture-diagrams

[Atharva-1512]

Fixes #12

Converted the ASCII decision flow diagram in ARCHITECTURE.md
to a Mermaid flowchart for better rendering and readability.

[rosspeili]

Thanks so much for taking the time to convert this @Atharva-1512 ! Moving the architecture diagram to Mermaid is a great idea and will definitely make the documentation cleaner and easier to read.

However, taking a look at the proposed flowchart logic, there are a few paths that don't quite match the actual execution flow in session.py:

1. Orchestrator Fall-through: If the orchestrator is due but decides to PASS, it skips its turn and execution falls through to the normal agent selection block. The current diagram makes [Speak or PASS] a dead end.
2. Mutually Exclusive Paths: After [Pick best agent], the flow arrow points directly to [Fallback: round robin]. This implies both happen sequentially. It should instead be a conditional branch (e.g., if the best agent score > 0, pick them; otherwise, fall back to round robin).
3. Non-Dynamic Sessions: If session_type is not dynamic, the flowchart ignores the fact that it could be ARGUMENTATIVE and currently routes directly to the generic fallback block.

I went ahead and drafted a revised version of the Mermaid syntax that captures these specific execution paths accurately. Feel free to copy this and update the PR with it!

flowchart TD

A[generate_next_turn()] --> B{Orchestrator due?}
B -->|Yes| C[Speak or PASS]
C -->|Speak| EndOrch[Append to history & return turn]
C -->|PASS| D

B -->|No| D{_forced_next_agent set?}
D -->|Yes| E[Use forced agent & clear flag] --> L
D -->|No| F{session_type = DYNAMIC?}

F -->|No| K[Fallback: round robin / argumentative] --> L
F -->|Yes| G{@mention in last message?}

G -->|Yes| H[Use mentioned agent] --> L
G -->|No| I[Score agents by expertise]

I --> J{Top score > 0?}
J -->|Yes| Best[Pick best matching agent] --> L
J -->|No| K

L[agent.generate_response()] --> M{response == PASS?}

M -->|Yes| N[Skip turn, return skipped: True]
M -->|No| O[Append to history with timestamp] --> P[Return turn_data]

Loading

[rosspeili]

P.S. It looks like this PR actually addresses Issue #12 (Mermaid docs) rather than Issue #18 (CLI tests)! You might want to update the PR description from Fixes #18 to Fixes #12 so the correct issue gets automatically closed.

[Atharva-1512]

@rosspeili I've made the necessary changes. Please review and suggest any further changes necessary. Thank you.

[rosspeili]

@Atharva-1512 I went ahead and manually updated the PR description to Fixes #12 instead of #18 for you so it automatically closes the correct issue. All the integration tests have passed successfully, and your changes are now officially merged into main!

Thanks a ton for your effort and for being so receptive to tweaking the diagram logic.

If you're interested in sticking around, feel free to check out the other good first issue tags we have open. We'd also love to hear any ideas you have for the project's future, once you've had a chance to run it locally and test it out with some different models, let us know if you spot anything missing, bugs that need fixing, or features that could make the framework even better. Don't hesitate to open new issues!

Thanks again for the contribution!

[Atharva-1512]

Thanks a lot for the support and for merging the PR!
I really enjoyed working on this and improving the diagram logic.
I’ll explore more issues and try contributing further. Also happy to suggest improvements once I test things locally.