How tenghu/actionweaver works
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