Stateful Graph DSL, CrewAI Agentic Metaphors, Secure Enterprise Toolb…

[Shekharmaheswari85]

🎯 Purpose and Scope

This PR introduces enterprise-scale enhancements to the relay-orchestrator library, competing directly with Python-heavy frameworks (CrewAI, LangGraph, and LangChain) while remaining idiomatic to Spring Boot, Spring AI, and Java patterns. It adds a stateful graph workflow DSL, a multi-agent hierarchy system, pre-packaged secure enterprise tools, virtual-thread concurrency, Actuator diagnostics, and complete documentation.

---

🚀 Key Implementations

1. Stateful Graph DSL (LangGraph-style)

• DSL Scaffolding: Added StateGraph<S> and thread-safe CompiledGraph<S> execution machines running node transitions on Java 21 Virtual Threads (Project Loom).
• Execution Flows: Supports loops, fixed edges (.addEdge), and dynamic runtime routing via conditional edges (.addConditionalEdge).
• Checkpoints & Rollbacks: Implemented GraphInterceptor<S> and DefaultDbSavingInterceptor<S> which serializes node execution state changes using Jackson to support time-travel state rollbacks and historical checkpoints.
• Human-in-the-Loop Interrupts: Added pause gates (triggered by target nodes like "WAIT_FOR_APPROVAL") with a .resume(state) portal.

2. Agentic Metaphors (CrewAI-style)

• High-level Abstractions: Introduced RelayAgent (with role, goal, backstory, and tools properties), RelayTask, and RelayCrew sequential/parallel kickoff orchestrators returning reactive streams.
• Persona Processing: Created AgentPersonaAdvisor to compile agent goals and backstories automatically, injecting them into Spring AI ChatClient system prompts.

3. Production-Grade Enterprise Toolbelt

• Secure databaseQuery: Wires Spring's JdbcTemplate as an optional dependency and implements a security guardrail allowing only read-only SELECT queries to prevent SQL injection mutations.
• secureRestCall: Standardized HTTP API dispatches utilizing Java 21 native HttpClient, ensuring zero external dependency overhead.
• fileSystemParser: Adds Path Traversal sandbox protection verifying normalized paths stay within System.getProperty("user.dir").

4. Process Engine & Diagnostics

• Concurrency: Created HierarchicalProcessEngine to execute tasks concurrently on Java Virtual Threads.
• Diagnostics: Built GraphDiagnosticsCollector exposed under Spring Actuator (/actuator/relaydiagnostics) to track node latencies, traversal counts, and token telemetry metrics.

5. Documentation

• Added detailed guides for Stateful Graph DSL, Crew Abstractions, and Enterprise Toolbelt.
• Updated docs/index.md, mkdocs.yml, and README.md.

---

🧪 Verification & Testing

All modules compile cleanly and the test suite passes successfully:

mvn clean test