# evilsocket/nerve architecture

> Architecture diagram of the GitHub repository evilsocket/nerve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evilsocket/nerve
- Repository: https://github.com/evilsocket/nerve

## Overview

##### Main Components
- CLI Interface (nerve/cli): This is where commands like “nerve create new-agent” or “nerve run new-agent” are handled. It gathers user inputs and invokes corresponding operations.
- Agent Parsing & Execution (YAML configuration files; examples directory illustrates various agent configurations): This component deals with reading and interpreting agent definitions written in YAML.
- Generation Module (nerve/generation): Handles conversation flows and interactions with large language models (LLMs). Files here (e.g., conversation.py, litellm.py, ollama.py) implement the logic for generating agent behaviors.
- Runtime Engine (nerve/runtime): Coordinates agent execution. Within this module, there are sub-components for:
- Managing agents (agent.py)
- Controlling workflow execution (flow.py)
- State management (state.py)
- Logging activities (logging.py)
- Handling events and concurrent operations via thread pool (thread_pool.py)
- Tools and Namespaces (nerve/tools): This includes a collection of utility functions and domain-specific implementations for various “namespaces.” For instance, tools for file system operations, shell commands, reasoning, etc. Each namespace (found under nerve/tools/namespaces) encapsulates tools for a specific domain.

##### Relationships and Interactions
- The CLI acts as the entry point—when a user initiates a command, it invokes the core logic found in the generation and runtime modules.
- The agent’s YAML definition (located in the examples or provided by the user) is parsed and then passed to the runtime engine to execute the defined task.
- The runtime layer interacts with the tools/namespaces to execute specific actions. For example, a “shell” namespace might be activated to run command-line instructions.
- The generation module interacts with language models to process instructions and possibly build conversational flows before sending tasks to the runtime.
- There is an internal flow between initiation (via CLI), processing (by generation), and execution (by runtime with support from tools/namespaces).

##### Architectural Patterns & Design Principles
- Modular Separation: The design clearly separates concerns between interfaces (CLI), processing (generation), and execution (runtime), with distinct utility modules (tools/namespaces) that encapsulate specific functionality.
- Plug-in/Extensibility: The rules for “namespaces” and tools imply that the system was designed with extensibility in mind; additional namespaces can be integrated without affecting the core architecture.
- Decoupled Workflow: By using YAML definitions for agents and designing executor modules (runtime), the framework allows dynamic behavior and easy modification or addition of new agents.

##### Relevant Technologies & Frameworks
- Python is the primary language, with packaging support via “pyproject.toml.”
- Docker support is evident via the Dockerfile and related CI/CD configurations in .github/workflows.
- CI tools (GitHub workflows) ensure quality and integration.
- For templating, the presence of Jinja2 template files (e.g., body.j2) in nerve/tools indicates dynamic content generation, likely used when constructing shell commands or other tool-specific instructions.

- CLI Interface (in nerve/cli)
- Generation Module (nerve/generation)
- Runtime Engine (nerve/runtime)
- Tools/Namespaces (nerve/tools and its subdirectories)
- From “CLI” to “Generation” and “Runtime” to show how user commands lead to processing and then execution.
- Between “Generation” and “Runtime” to indicate that decisions (or conversational outputs) from the generation module directly influence runtime behavior.
- From “Runtime” pointing to “Tools/Namespaces” to show delegation of specific task operations.
5. External influences like configuration files and CI/CD pipelines (e.g., a note that CI workflows build and test the Docker image).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Nerve ADK"
        CLI["CLI Interface"]:::cli
        Generation["Generation Module"]:::gen
        Runtime["Runtime Engine"]:::runtime
        Tools["Tools/Namespaces"]:::tools
    end

    YAML["YAML Agent Definitions"]:::config
    User["User Command"]:::external
    CICD["CI/CD & Docker"]:::external

    User -->|"initiate"| CLI
    CLI -->|"command_execution"| Generation
    CLI -->|"command_execution"| Runtime
    Generation -->|"instruction_parsing"| Runtime
    YAML -->|"agent_configuration"| Runtime
    Runtime -->|"tool_invocation"| Tools
    CICD -->|"build_test_deploy"| Runtime

    click CLI "https://github.com/evilsocket/nerve/blob/main/nerve/cli/agents.py"
    click CLI "https://github.com/evilsocket/nerve/blob/main/nerve/cli/create.py"
    click CLI "https://github.com/evilsocket/nerve/blob/main/nerve/cli/run.py"
    click YAML "https://github.com/evilsocket/nerve/tree/main/examples"
    click Generation "https://github.com/evilsocket/nerve/blob/main/nerve/generation/conversation.py"
    click Generation "https://github.com/evilsocket/nerve/blob/main/nerve/generation/litellm.py"
    click Generation "https://github.com/evilsocket/nerve/blob/main/nerve/generation/ollama.py"
    click Runtime "https://github.com/evilsocket/nerve/blob/main/nerve/runtime/agent.py"
    click Runtime "https://github.com/evilsocket/nerve/blob/main/nerve/runtime/flow.py"
    click Runtime "https://github.com/evilsocket/nerve/blob/main/nerve/runtime/state.py"
    click Runtime "https://github.com/evilsocket/nerve/blob/main/nerve/runtime/logging.py"
    click Runtime "https://github.com/evilsocket/nerve/blob/main/nerve/runtime/thread_pool.py"
    click Tools "https://github.com/evilsocket/nerve/blob/main/nerve/tools/namespaces/shell.py"
    click Tools "https://github.com/evilsocket/nerve/blob/main/nerve/tools/namespaces/filesystem.py"
    click Tools "https://github.com/evilsocket/nerve/blob/main/nerve/tools/namespaces/time.py"

    classDef cli fill:#f9d5e5,stroke:#d17fa6,stroke-width:2px;
    classDef gen fill:#d5e8d4,stroke:#82b366,stroke-width:2px;
    classDef runtime fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px;
    classDef tools fill:#fff2cc,stroke:#d6b656,stroke-width:2px;
    classDef config fill:#fce5cd,stroke:#e69138,stroke-width:2px;
    classDef external fill:#d5e1df,stroke:#95a5a6,stroke-width:2px;
```
