← Back to Foundation

JIDO BUILDOUT gem

Documentation for JIDO_BUILDOUT_gem from the Foundation repository.

Of course. Based on the provided foundation codebase and the jido/jido_action guides, here is a proposed architecture for the new jido module, along with an enhanced example application that showcases the full power of the integrated stack.

Architecture Proposal: The Jido Application Layer

The foundation project provides robust, production-grade infrastructure primitives (Registry, Coordination, Error Handling, etc.). The jido and jido_action guides describe a developer-friendly framework for building agents and workflows. The goal is to build the jido framework on top of the foundation platform, creating a powerful, layered system.

The new module, which we will call Jido, will live in lib/jido/ (as lib/nextModule implies). It will not reinvent the wheel but will serve as the primary interface for developers, intelligently composing foundation primitives and integrating the jido_action execution engine.

Directory Structure for lib/jido/

lib/
├── jido/
│   ├── agent/
│   │   ├── directive.ex      # Defines agent directives (Enqueue, RegisterAction, Spawn, etc.)
│   │   ├── runner.ex         # Runner behaviour (Simple, Chain)
│   │   ├── server.ex         # The GenServer implementation for stateful agents
│   │   └── supervisor.ex     # Agent's own child supervisor
│   ├── sensor/
│   │   └── heartbeat.ex      # Example built-in sensor
│   ├── signal/
│   │   ├── router.ex         # Signal routing logic (like in jido_foundation)
│   │   └── signal.ex         # The Signal struct and helpers
│   ├── agent.ex              # The main `use Jido.Agent` macro
│   ├── application.ex        # The Jido OTP application
│   ├── sensor.ex             # The `use Jido.Sensor` macro
│   ├── skill.ex              # The `use Jido.Skill` macro
│   └── supervisor.ex         # Top-level Jido supervisor
└── jido.ex                   # Top-level facade (optional)

Key Integration Points and Architectural Decisions

  1. Jido.Agent (The Core Abstraction):

    • The use Jido.Agent macro will be the primary entry point for developers.
    • It will handle state management, instruction queuing, and action registration as described in the guides.
    • Integration: When a stateful agent (Jido.Agent.Server) starts, it will automatically call Foundation.register/4 to register itself with the configured registry_impl. The metadata will be rich, including the agent’s name, capabilities (derived from its actions and skills), and initial health status.
    • It will start its own Jido.Agent.Supervisor to manage its child processes (sensors or other agents).

  2. Jido.Agent.Server (The Stateful Engine):

    • This GenServer is the runtime for a stateful agent. It manages the agent’s state, instruction queue, and lifecycle.
    • Integration: It will trap exits and, upon termination, use Foundation.unregister/2 to clean up its entry in the registry. This leverages Foundation’s robust monitoring capabilities.

  3. Jido.Action and Jido.Exec (The Execution Layer):

    • The Jido module will not reimplement action execution. It will use the provided jido_action library’s Jido.Exec module.
    • Integration: The Jido.Agent.Runner (e.g., ChainRunner) will call Jido.Exec.run/4. We will enhance or wrap Jido.Exec to integrate with Foundation:
      • Resource Management: Before executing a resource-intensive action (marked with a new @tag :heavy), it will call Foundation.ResourceManager.acquire_resource/2.
      • Circuit Breakers: For actions that involve external calls (@tag :external_api), it will wrap the execution in Foundation.execute_protected/4. This provides resilience without the developer needing to think about it.

  4. Jido.Signal (The Communication Bus):

    • The JidoFoundation.SignalRouter is a perfect prototype. This will be formalized into Jido.Signal.Router.
    • Integration: The router will use telemetry as its underlying transport. Agents emit signals, which are captured by the router. The router then uses Foundation.query/2 to find agents subscribed to specific signal patterns (e.g., agents with a skill that handles "error.*"). This is a powerful, decoupled communication pattern.

  5. Jido.Skill (The Extensibility Layer):

    • A Skill will be a module that bundles actions, routes, and sensors.
    • When an agent uses a Skill, the agent’s start_link will automatically:
      1. Register the skill’s actions.
      2. Add the skill’s routes to its Jido.Signal.Router.
      3. Start the skill’s sensors under its own supervisor.
    • Integration: This allows complex capabilities, built on Foundation, to be encapsulated and reused. For example, a MLFoundation.TeamOrchestration skill could be added to an agent to give it team management abilities.

Enhanced Example Application: Distributed Content Moderation System

This example goes beyond simple CRUD-like actions to showcase a dynamic, resilient, and observable multi-agent system built on the full stack.

Goal: Create a system that receives content (text, images), analyzes it for policy violations, and takes appropriate action.

1. The Agents

  • TriageAgent (The Router):

    • Role: The system’s entry point. Receives new content submissions.
    • Logic:
      1. Receives a signal like {type: "content.submitted", data: %{content_type: :text, payload: "..."}}.
      2. Uses MABEAM.Discovery.find_capable_and_healthy(:text_analysis) to find an available text analysis agent.
      3. If no agent is available, it can either hold the content in a queue or use a Foundation.Coordination primitive to request a new analysis agent be spawned.
      4. Forwards the content to the chosen analysis agent.

  • TextAnalysisAgent (The Specialist):

    • Role: Analyzes text for violations.
    • Skill: use Jido.Skill, TextAnalysisSkill
    • Actions within the Skill:
      • CheckToxicityAction: Calls an external AI/LLM to score for toxicity. Integration: This action is tagged @tag :external_api and its execution is wrapped by Foundation.execute_protected to provide circuit-breaker resilience. If the API is down, it can return a cached/default result.
      • DetectPIIAction: Scans for Personally Identifiable Information.
      • GenerateAnalysisReportAction: Compiles the results.
    • Workflow: Chains these actions. Upon completion, emits a content.analysis.completed signal with the report.

  • ImageAnalysisAgent (The Heavy-Lifting Specialist):

    • Role: Analyzes images for violations. This is a resource-intensive task.
    • Skill: use Jido.Skill, ImageAnalysisSkill
    • Actions within the Skill:
      • AnalyzeImageAction: Performs the analysis. Integration: This action is tagged @tag :heavy. Before Jido.Exec runs it, it calls Foundation.ResourceManager.acquire_resource(:image_processing). If resources are unavailable, the request is rejected or requeued, preventing system overload. After completion, the resource is released.
    • Workflow: Emits content.analysis.completed signal.

  • PolicyEnforcementAgent (The Decider):

    • Role: Subscribes to content.analysis.completed signals. Makes the final moderation decision.
    • Logic:
      1. Receives the analysis report.
      2. If the report is ambiguous, it uses Foundation.Coordination.start_consensus with other PolicyEnforcementAgent instances to vote on the final action.
      3. Executes a final action chain: [DetermineAction, ExecuteAction, LogAction].
      • ExecuteAction could be BanUserAction, DeleteContentAction, etc. Integration: These critical actions are wrapped in Foundation.AtomicTransaction to ensure that, for example, a user is marked as banned and their content is deleted in a single, all-or-nothing operation.

2. How it Showcases the Full Stack

  • jido (Application Framework): Provides the high-level Agent, Skill, Sensor, and Action abstractions that make the logic easy to write and reason about. The entire workflow is described as a series of Jido actions and signals.

  • jido_action (Execution Engine): The Jido.Exec and Jido.Exec.Chain modules are used by the agents’ runners to execute the action pipelines, handling parameter passing and result aggregation.

  • foundation (The Platform):

    • Foundation.Registry (MABEAM.AgentRegistry): All agents are registered. The TriageAgent uses it for dynamic, health-aware discovery of workers. This is far more robust than hardcoding PIDs.
    • Foundation.Infrastructure (MABEAM.AgentInfrastructure):
      • The TextAnalysisAgent’s external API call is protected by a circuit breaker.
      • The ImageAnalysisAgent’s heavy workload is managed by the ResourceManager, preventing it from crashing the node.
    • Foundation.Coordination (MABEAM.AgentCoordination): The PolicyEnforcementAgent uses consensus to make resilient, distributed decisions, avoiding a single point of failure in judgment.
    • Foundation.AtomicTransaction: The PolicyEnforcementAgent uses atomic transactions to ensure critical, multi-step state changes (like banning a user and deleting their content) are applied consistently.
    • Foundation.PerformanceMonitor: Could be used by a SystemMonitorAgent to track action execution times and system load, triggering alerts or auto-scaling actions.

This example demonstrates a system that is not only logically sound (separating triage, analysis, and enforcement) but also robust, observable, and scalable, thanks to the deep integration of the developer-friendly Jido framework with the production-ready Foundation platform.