# adam-h-ds/tinyagents architecture

> Architecture diagram of the GitHub repository adam-h-ds/tinyagents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adam-h-ds/tinyagents
- Repository: https://github.com/adam-h-ds/tinyagents

## Overview

##### Project type and purpose
- TinyAgents is an open-source Python library for building and orchestrating agentic applications using a lightweight graph DSL.
- It provides decorators to wrap existing functions or classes as “chainable” nodes, compiles graphs into runners, and optionally integrates with Ray Serve and OpenTelemetry tracing.

##### File structure
- **Core package** (`tinyagents/`):
- graph.py – graph builder, compile & invoke API
- decorators.py, callbacks.py, handlers.py – glue code for node execution & lifecycle hooks
- deployment_utils.py – Ray Serve integration
- tracing/ – OpenTelemetry instrumentation
- utils.py, types.py – shared utilities and type definitions
- **Configuration**: `pyproject.toml`, `mypy.ini`
- **CI/CD**: `.github/workflows/publish.yml`
- **Docs & Examples**: `docs/`, `examples/`
- **Tests**: `test/`
- **Metadata**: `README.md`, `LICENSE`, `.gitignore`

##### README for additional insights
- Two execution backends:
a. **Local executor** (ThreadPoolExecutor)
b. **Ray Serve** (via `deployment_utils`)
- Tracing via OpenTelemetry following OpenInference conventions, visualizable in Arize Phoenix.

1. **User application**
- Chainable functions & classes decorated by `@chainable`
- Graph definition (using operators `|`, `&`, `/`, `loop()`)
2. **TinyAgents core**
- Graph Builder (tinyagents/graph.py)
- Node Types (tinyagents/nodes/)
- Decorators & Callbacks
- Utils & Types
3. **Execution Layer**
- Local Executor (ThreadPoolExecutor)
- Ray Serve Deployment (deployment_utils.py → Ray Serve cluster)
4. **Tracing**
- OpenTelemetry instrumentation (tinyagents/tracing/)
- External Collector / Arize Phoenix
5. **CI/CD & Packaging**
- GitHub Actions → PyPI publishing
- Configuration files
- From **User App** → **Graph Builder**: “define & compile graph”
- **Graph Builder** → **Execution Layer**: “runner.invoke()”
- **Execution Layer** → Node implementations (via decorators, callbacks)
- **Execution Layer** → **Tracing**: “emit spans” → **Collector**
- **Ray Serve** path: Graph Builder (compile with `use_ray=True`) → Ray deployments → client requests
c. Architectural patterns & principles
- **DSL / Fluent API** for graph composition
- **Decorator pattern** to wrap user code as nodes
- **Strategy pattern** for pluggable executors (ThreadPool vs Ray)
- **OpenTelemetry instrumentation** inserted transparently when enabled
d. Key technologies & frameworks
- Python 3.8+
- ThreadPoolExecutor (stdlib)
- Ray & Ray Serve
- OpenTelemetry (semantic conventions from OpenInference)
- Pydantic (in examples)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% User Application
  subgraph "User Application" 
    UA1["Deploy with Ray Example"]:::blue
    UA2["Legal Researcher Example"]:::blue
  end

  %% Core Library
  subgraph "TinyAgents Core"
    CB["Graph Builder (graph.py)"]:::green
    subgraph "Node Types" 
      NP["Parallel Node"]:::green
      NC["ConditionalBranch Node"]:::green
      NR["Recursive (Loop) Node"]:::green
      NS["SubGraph Node"]:::green
      NM["Node Metadata"]:::green
    end
    subgraph "Decorators & Hooks"
      DC["Decorators"]:::green
      CBK["Callbacks"]:::green
      HD["Handlers"]:::green
    end
    subgraph "Utils & Types"
      UT["Utilities"]:::green
      TY["Type Definitions"]:::green
    end
  end

  %% Execution Layer
  subgraph "Execution Layer"
    LE["Local Executor\n(ThreadPoolExecutor)"]:::orange
    RS["Ray Serve Deployment"]:::orange
  end

  %% Tracing
  subgraph "Tracing"
    TDc["Tracing Decorators"]:::purple
    TU["Tracing Utilities"]:::purple
    EC["External Collector\n(Arize Phoenix)"]:::purple
  end

  %% Configuration & CI
  subgraph "Configuration & CI/CD"
    PC["pyproject.toml / mypy.ini"]:::grey
    CI["GitHub Actions\n(publish.yml)"]:::grey
  end

  %% Documentation
  subgraph "Documentation"
    DG["docs/using_ray.md\n& assets"]:::grey
  end

  %% Tests
  subgraph "Tests"
    TG["test_graph.py"]:::grey
    TP["test_parallel.py"]:::grey
    TB["test_branch.py"]:::grey
    TR["test_recursive.py"]:::grey
    TT["test_tracing.py"]:::grey
  end

  %% Connections
  UA1 -->|"uses chainable & defines graph"| CB
  UA2 -->|"uses chainable & defines graph"| CB

  CB -->|"builds nodes"| NP
  CB --> NP
  CB --> NC
  CB --> NR
  CB --> NS
  CB --> NM

  CB --> DC
  CB --> CBK
  CB --> HD

  DC --> LE
  CBK --> LE
  HD --> LE

  LE -->|"invoke runner"| CB
  CB -->|"compile(use_ray=True)"| RS

  LE -->|"emit spans"| TDc
  RS -->|"emit spans"| TDc
  TDc --> TU
  TU --> EC

  PC --> CI
  DG --> UA1
  DG --> UA2

  TG --> CB
  TP --> NP
  TB --> NC
  TR --> NR
  TT --> TDc

  %% Click Events
  click UA1 "https://github.com/adam-h-ds/tinyagents/blob/main/examples/deploy_with_ray.ipynb"
  click UA2 "https://github.com/adam-h-ds/tinyagents/blob/main/examples/legal_researcher.ipynb"
  click CB "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/graph.py"
  click NP "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/nodes/parallel.py"
  click NC "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/nodes/conditional_branch.py"
  click NR "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/nodes/recursive.py"
  click NS "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/nodes/subgraph.py"
  click NM "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/nodes/node_meta.py"
  click DC "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/decorators.py"
  click CBK "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/callbacks.py"
  click HD "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/handlers.py"
  click UT "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/utils.py"
  click TY "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/types.py"
  click RS "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/deployment_utils.py"
  click TDc "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/tracing/decorators.py"
  click TU "https://github.com/adam-h-ds/tinyagents/blob/main/tinyagents/tracing/utils.py"
  click PC "https://github.com/adam-h-ds/tinyagents/blob/main/pyproject.toml"
  click CI "https://github.com/adam-h-ds/tinyagents/blob/main/.github/workflows/publish.yml"
  click DG "https://github.com/adam-h-ds/tinyagents/blob/main/docs/using_ray.md"
  click TG "https://github.com/adam-h-ds/tinyagents/blob/main/test/test_graph.py"
  click TP "https://github.com/adam-h-ds/tinyagents/blob/main/test/test_parallel.py"
  click TB "https://github.com/adam-h-ds/tinyagents/blob/main/test/test_branch.py"
  click TR "https://github.com/adam-h-ds/tinyagents/blob/main/test/test_recursive.py"
  click TT "https://github.com/adam-h-ds/tinyagents/blob/main/test/test_tracing.py"

  %% Styles
  classDef blue fill:#A7C7E7,stroke:#333,stroke-width:1px;
  classDef green fill:#9FE2BF,stroke:#333,stroke-width:1px;
  classDef orange fill:#FFD580,stroke:#333,stroke-width:1px;
  classDef purple fill:#DDA0DD,stroke:#333,stroke-width:1px;
  classDef grey fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
