# tenghu/actionweaver architecture

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

- Interactive diagram: https://gitdiagram.com/tenghu/actionweaver
- Repository: https://github.com/tenghu/actionweaver

## Overview

##### Project type and purpose
- ActionWeaver is a Python library/framework for building AI-driven applications that center function-calling as a first-class concept.
- It wraps OpenAI or Azure OpenAI chat-completion APIs, manages the function-call loop, provides decorators/factories to turn Python code or Pydantic models into “actions,” supports orchestration of chained actions, and offers telemetry/exception-handling hooks.

##### File structure
- Top-level module: actionweaver/
- actions/            – definitions, base Action class, and factories (combine, repeat, function, pydantic_model_to_action, langchain, etc.)
- llms/               – wrapper, provider adapters (openai, azure, general), chat loop, action processor, exception handling
- mixins/             – optional example mixins (folium, langchain, openai)
- telemetry/          – helpers for structured logging/tracing (e.g., LangSmith integration)
- utils/              – shared utilities (caching, streaming, token counting, output formatting, Pydantic helpers)
- Configuration/build: pyproject.toml, .readthedocs.yaml
- Documentation: docs/ (source, notebooks, cookbooks)
- Test suites mirror modules under tests/

##### README for additional insights
- Confirms core concepts: `wrap` function for client, `@action` decorator, factories for converting Pydantic models, orchestration via `orch`, exception handler API
- Highlights supported LLM back-ends (OpenAI, Azure), emphasizes extensibility and observability

##### Main components
a. Developer Code
- Defines actions (via `@action` or `action_from_model`)
- Configures orchestration mapping (`orch`)
- Instantiates and wraps an OpenAI/Azure client with `wrap(...)`
- Calls `.create(...)` or `.invoke(...)` on actions
b. ActionWeaver SDK Layers
1. Public API Layer
- wrap() adapter
- action decorator / factory methods
- ExceptionHandler interface
2. Core Engine
- ChatLoop (orchestration of LLM calls and function invocations)
- ActionProcessor (routes LLM’s function-calling requests to Python functions)
- Orchestration logic (`orch` state machine)
3. LLM Provider Adapters
- azure/chat.py, openai/chat.py, general/chat.py
- wrapper adds “actions” and intercepts responses
4. Actions Module
- Base Action class
- Factories: combine, repeat, pydantic_model_to_action, langchain integration
5. Telemetry & Observability
- Telemetry helpers for structured logs, LangSmith tracing
6. Utilities
- Caching, streaming, Pydantic helpers, token counting, output formatting
c. External Services
- OpenAI or Azure OpenAI REST API endpoints
- (Optional) LangSmith or other telemetry back-end

##### Relationships and data flow
1. Developer code ➔ calls wrap(OpenAI/AzureOpenAI) ➔ returns wrapped client
2. Developer sets up actions + orch mapping, then calls client.create(...)
3. Public API Layer serializes “actions” into JSON‐schema functions and attaches to chat request
4. Wrapped client forwards request to LLM Provider Adapter
5. LLM returns either:
- A function call with name + arguments
- A normal chat response
6. ChatLoop inspects response:
- If function call → ActionProcessor looks up corresponding Python function or Pydantic model action → invokes it → captures result
- If exception raised → calls user-provided ExceptionHandler.handle_exception → decide “Continue” or “Return”
- Based on orchestration mapping, decide next set of actions or terminate loop
7. Loop until LLM returns non-function response → final chat content returned to developer
8. Telemetry helpers log each step, optionally stream to LangSmith

##### Architectural patterns & design principles
- Adapter/Wrapper pattern for LLM providers
- Decorator and Factory patterns for action definitions
- State-machine orchestration (orch mapping)
- Strategy pattern for exception handling
- Modular separation: public API, core engine, provider adapters, actions, telemetry, utils
- Use of Pydantic for schema validation and generation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Zone A: Developer
    subgraph "Zone A: Developer"
        DeveloperCode["Define actions & orch mapping"]:::developer
        WrapCall["Call wrap(OpenAI/Azure)"]:::developer
        InvokeAction["Invoke action.create()/invoke()"]:::developer
    end

    %% Zone B: ActionWeaver SDK
    subgraph "Zone B: ActionWeaver SDK"

        %% Public API Layer
        subgraph "Public API Layer"
            Wrap["wrap()"]:::api
            Decorator["action decorator"]:::api
            FactoryFunc["function factory"]:::api
            FactoryModel["pydantic_model_to_action"]:::api
            FactoryCombine["combine factory"]:::api
            FactoryRepeat["repeat factory"]:::api
            FactoryLangchain["langchain factory"]:::api
            FactoryInstructor["instructor factory"]:::api
            ExceptionHandler["ExceptionHandler interface"]:::api
        end

        %% Core Engine
        subgraph "Core Engine"
            ChatLoopAzure["Azure ChatLoop"]:::core
            ChatLoopOpenAI["OpenAI ChatLoop"]:::core
            ActionProcessor["ActionProcessor"]:::core
            Orchestration["Orchestration (orch)"]:::core
        end

        %% LLM Provider Adapters
        subgraph "LLM Provider Adapters"
            AzureChat["Azure chat adapter"]:::adapter
            OpenAIFuncChat["OpenAI functions adapter"]:::adapter
            GeneralChat["General chat adapter"]:::adapter
            AzureFuncs["Azure functions definitions"]:::adapter
            OpenAIFuncs["OpenAI functions registry"]:::adapter
            OpenAITools["OpenAI tools definitions"]:::adapter
            GeneralTools["General tools definitions"]:::adapter
        end

        %% Actions Module
        subgraph "Actions Module"
            BaseAction["Base Action class"]:::actions
            Combine["combine factory"]:::actions
            Repeat["repeat factory"]:::actions
            Langchain["langchain integration"]:::actions
            Instructor["instructor factory"]:::actions
        end

        %% Telemetry & Observability
        subgraph "Telemetry & Observability"
            TelemetryHelpers["Telemetry helpers"]:::telemetry
        end

        %% Utilities
        subgraph "Utilities"
            Caching["Caching"]:::utils
            Streaming["Streaming"]:::utils
            TokenCount["Token counting"]:::utils
            OutputFmt["Output formatting"]:::utils
            PydanticUtils["Pydantic helpers"]:::utils
            ActionScope["Action scoping"]:::utils
        end

    end

    %% Zone C: External
    subgraph "Zone C: External"
        LLMService((OpenAI/Azure API)):::external
        TelemetryBackend((LangSmith Back-end)):::external
    end

    %% Connections
    DeveloperCode -->|"defines actions & orch"| Decorator
    DeveloperCode --> FactoryFunc
    DeveloperCode --> FactoryModel
    DeveloperCode --> FactoryCombine
    DeveloperCode --> FactoryRepeat
    DeveloperCode --> FactoryLangchain
    DeveloperCode --> FactoryInstructor

    DeveloperCode --> ExceptionHandler
    WrapCall --> Wrap
    Wrap --> AzureChat
    Wrap --> OpenAIFuncChat
    Wrap --> GeneralChat

    InvokeAction --> Wrap
    Wrap -->|"chat request + function schemas"| AzureChat
    AzureChat -->|"HTTP request"| LLMService
    OpenAIFuncChat -->|"HTTP request"| LLMService
    GeneralChat -->|"HTTP request"| LLMService

    LLMService -->|"response"| ChatLoopAzure
    LLMService -->|"response"| ChatLoopOpenAI

    ChatLoopAzure --> ActionProcessor
    ChatLoopOpenAI --> ActionProcessor
    ActionProcessor --> BaseAction
    ActionProcessor --> Combine
    ActionProcessor --> Repeat
    ActionProcessor --> Langchain
    ActionProcessor --> Instructor
    ActionProcessor -->|"invokes Python fn"| DeveloperCode

    ChatLoopAzure --> Orchestration
    ChatLoopOpenAI --> Orchestration
    Orchestration --> AzureChat
    Orchestration --> OpenAIFuncChat
    Orchestration --> GeneralChat

    ChatLoopAzure --> TelemetryHelpers
    ChatLoopOpenAI --> TelemetryHelpers
    ActionProcessor --> TelemetryHelpers
    Orchestration --> TelemetryHelpers
    TelemetryHelpers --> TelemetryBackend

    %% Click Events
    click Wrap "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/wrapper.py"
    click Decorator "https://github.com/tenghu/actionweaver/blob/main/actionweaver/actions/action.py"
    click FactoryFunc "https://github.com/tenghu/actionweaver/blob/main/actionweaver/actions/factories/function.py"
    click FactoryModel "https://github.com/tenghu/actionweaver/blob/main/actionweaver/actions/factories/pydantic_model_to_action.py"
    click FactoryCombine "https://github.com/tenghu/actionweaver/blob/main/actionweaver/actions/factories/combine.py"
    click FactoryRepeat "https://github.com/tenghu/actionweaver/blob/main/actionweaver/actions/factories/repeat.py"
    click FactoryLangchain "https://github.com/tenghu/actionweaver/blob/main/actionweaver/actions/factories/langchain.py"
    click FactoryInstructor "https://github.com/tenghu/actionweaver/blob/main/actionweaver/actions/factories/instructor.py"
    click ExceptionHandler "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/exception_handler.py"
    click ChatLoopAzure "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/azure/chat_loop.py"
    click ChatLoopOpenAI "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/openai/tools/chat_loop.py"
    click ActionProcessor "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/general/action_processor.py"
    click Orchestration "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/loop_action.py"
    click AzureChat "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/azure/chat.py"
    click OpenAIFuncChat "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/openai/functions/chat.py"
    click GeneralChat "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/general/chat.py"
    click AzureFuncs "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/azure/functions.py"
    click OpenAIFuncs "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/openai/functions/functions.py"
    click OpenAITools "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/openai/tools/tools.py"
    click GeneralTools "https://github.com/tenghu/actionweaver/blob/main/actionweaver/llms/general/tools.py"
    click TelemetryHelpers "https://github.com/tenghu/actionweaver/blob/main/actionweaver/telemetry/helpers.py"
    click Caching "https://github.com/tenghu/actionweaver/blob/main/actionweaver/utils/cache.py"
    click Streaming "https://github.com/tenghu/actionweaver/blob/main/actionweaver/utils/stream.py"
    click TokenCount "https://github.com/tenghu/actionweaver/blob/main/actionweaver/utils/tokens.py"
    click OutputFmt "https://github.com/tenghu/actionweaver/blob/main/actionweaver/utils/output.py"
    click PydanticUtils "https://github.com/tenghu/actionweaver/blob/main/actionweaver/utils/pydantic_utils.py"
    click ActionScope "https://github.com/tenghu/actionweaver/blob/main/actionweaver/utils/action_scope.py"

    %% Styles
    classDef developer fill:#D6E9C6,stroke:#333,stroke-width:1px
    classDef api fill:#C6E0F5,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef core fill:#E2EFDA,stroke:#333,stroke-width:1px
    classDef adapter fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef actions fill:#FCE4D6,stroke:#333,stroke-width:1px
    classDef telemetry fill:#D9D9D9,stroke:#333,stroke-width:1px
    classDef utils fill:#E6E0EC,stroke:#333,stroke-width:1px
    classDef external fill:#F8CECC,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2,shape:cylinder
```
