https://github.com/aygp-dr/llm-function-actors
Two-actor pattern implementation for LLM function calling in Guile Scheme. Demonstrates message passing, async actors, and extensible function registry for AI tool use.
https://github.com/aygp-dr/llm-function-actors
actor-model ai-agents function-calling guile llm scheme
Last synced: 4 months ago
JSON representation
Two-actor pattern implementation for LLM function calling in Guile Scheme. Demonstrates message passing, async actors, and extensible function registry for AI tool use.
- Host: GitHub
- URL: https://github.com/aygp-dr/llm-function-actors
- Owner: aygp-dr
- Created: 2025-07-22T11:15:15.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-24T09:07:13.000Z (11 months ago)
- Last Synced: 2025-10-31T00:40:23.512Z (7 months ago)
- Topics: actor-model, ai-agents, function-calling, guile, llm, scheme
- Language: Scheme
- Size: 138 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.org
Awesome Lists containing this project
README
#+TITLE: LLM Function Calling Pattern - Two Actor System
#+PROPERTY: header-args :mkdirp yes :comments both
[[https://img.shields.io/badge/language-Guile%20Scheme-blue.svg]]
[[https://img.shields.io/badge/license-MIT-green.svg]]
[[https://img.shields.io/badge/platform-FreeBSD%20%7C%20Linux-lightgrey.svg]]
A Guile Scheme implementation demonstrating the interaction between an Application (Actor 1) and an LLM Provider (Actor 2) for function calling capabilities.
#+begin_src ditaa :file llm-function-arch.png :exports results
+---------------+ +---------------+
| Application |<----->| LLM |
| Actor | | Actor |
+-------+-------+ +-------+-------+
| |
v v
+-------+-------+ +-------+-------+
| Function | | Decision |
| Registry | | Engine |
+---------------+ +---------------+
#+end_src
#+begin_src mermaid :file llm-function-calling-flow.png :exports results
graph TD
A[User Prompt] --> B{Analyze Intent}
B --> C{Tool Relevant?}
C -->|Yes| D[Select Tool]
C -->|No| E[Direct Response]
D --> F{Parameters Clear?}
F -->|Yes| G[Call Function]
F -->|No| H[Ask Clarification]
G --> I{Need More Tools?}
I -->|Yes| D
I -->|No| J[Generate Response]
H --> K[User Clarifies]
K --> F
E --> L[Return Answer]
J --> L
style A fill:#f9f,stroke:#333,stroke-width:2px
style L fill:#9f9,stroke:#333,stroke-width:2px
style C fill:#ff9,stroke:#333,stroke-width:2px
style I fill:#ff9,stroke:#333,stroke-width:2px
#+end_src
[[./docs/llm-function-calling-sequence.mmd][View detailed sequence diagram]]
#+begin_src dot :file llm-function-states.png :cmd dot :cmdline -Tpng :exports results
digraph G {
rankdir=TB;
node [shape=box, style=rounded];
Start [shape=circle, label=""];
Idle [label="Idle"];
Prompt [label="Prompt\nReceived"];
Request [label="Preparing\nRequest"];
Waiting [label="Waiting\nfor LLM"];
Processing [label="Processing\nResponse"];
FunctionCall [label="Function Call\nDetected"];
Execute [label="Executing\nFunction"];
Final [label="Final\nAnswer"];
End [shape=doublecircle, label=""];
Start -> Idle;
Idle -> Prompt [label="User Input"];
Prompt -> Request;
Request -> Waiting [label="Send Request"];
Waiting -> Processing;
Processing -> FunctionCall [label="Has Tool Call"];
Processing -> Final [label="Direct Response"];
FunctionCall -> Execute;
Execute -> Waiting [label="Send Result"];
Final -> End;
}
#+end_src
** Overview
This project implements a two-actor pattern for LLM function calling, providing:
- Clear separation between application logic and LLM reasoning
- Asynchronous message passing between actors
- Extensible function registry
- Thread-safe communication channels
** Architecture
The system consists of two main actors:
1. *Application Actor*: Manages function definitions, executes requested functions, and handles results
2. *LLM Actor*: Processes prompts, decides whether to call functions or respond directly, and generates final answers
Communication happens through message queues with defined message types for each phase of interaction.
** Requirements
- GNU Guile 3.0 or later
- SRFI modules (srfi-1, srfi-9)
- ice-9 modules (match, format, threads)
** Installation
#+begin_src bash
git clone https://github.com/aygp-dr/llm-function-actors
cd llm-function-actors
#+end_src
** Usage
*** Run the simulator
#+begin_src bash
gmake run
#+end_src
*** Run demo examples
#+begin_src bash
gmake demo
# or directly:
./examples/function-calling-demo.scm
#+end_src
*** Available Functions
The simulator comes with two built-in functions:
- ~calculate~: Adds two numbers
- ~get-time~: Returns current timestamp
Additional functions can be registered:
#+begin_src scheme
(register-function! 'my-function
(lambda (arg1 arg2)
;; function implementation
result))
#+end_src
** Project Structure
#+begin_example
.
├── SETUP.org # Original design document
├── README.org # This file
├── Makefile # Build automation
├── src/
│ └── function-calling-simulator.scm # Main simulator
├── examples/
│ └── function-calling-demo.scm # Usage examples
└── docs/
├── function-flow.org # Sequence diagrams
└── pattern-analysis.org # Architecture analysis
#+end_example
** Message Flow
1. Application sends initial prompt with function definitions
2. LLM analyzes prompt and decides action
3. If function needed: LLM requests function execution
4. Application executes function and returns result
5. LLM incorporates result and generates final answer
** Extending the System
To add new capabilities:
1. Register new functions using ~register-function!~
2. Extend message types for new interaction patterns
3. Add error handling for production use
4. Implement timeout mechanisms for long-running functions
** License
This project is part of the aygp-dr repository.