# roy-alpha/call-me-maybe architecture

> Architecture diagram of the GitHub repository roy-alpha/call-me-maybe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roy-alpha/call-me-maybe
- Repository: https://github.com/roy-alpha/call-me-maybe

## Overview

1. **What this repo is**
   - `Call-Me-Maybe` is a small, local function-calling pipeline for Python 3.10+.
   - Its main goal is to map a natural-language prompt to:
     - one function name from a provided catalog, and
     - a typed argument payload for that function.
   - The architecture is built around **constrained decoding** rather than free-form text generation.

2. **Top-level execution path**
   - The runtime entry point is `src/__main__.py`, which routes into the CLI layer in `src/core/cli.py`.
   - The CLI parses paths for:
     - `functions_definition.json`
     - input prompts/test cases
     - output file location
   - The CLI then delegates the actual work to the orchestration layer in `src/core/engine.py`.

3. **Input and validation boundary**
   - `src/core/validators.py` is the schema gate for the repo.
   - It validates the JSON structures for function definitions and prompt/test inputs before any model call happens.
   - This boundary is important because the rest of the system assumes the function catalog, parameter types, and prompt format are structurally correct.

4. **Core orchestration layer**
   - `src/core/engine.py` is the main coordinator.
   - It likely performs the full sequence:
     - load and validate inputs,
     - load the model/tokenizer abstraction,
     - build function-name constraints,
     - run function selection,
     - run parameter extraction,
     - write the final structured result to disk.
   - This file is the best place to anchor an architecture diagram’s “application logic” box.

5. **Model boundary**
   - The `llm_sdk/` package is the abstraction boundary for the language model runtime.
   - Based on the README, the system is designed to run against **local Hugging Face models** and use the model’s tokenizer/logits directly.
   - This package is where the repo separates “model access” from “decoding logic,” which keeps the core engine model-agnostic.

6. **Function-selection subsystem**
   - The repository’s distinguishing feature is the function-name selector.
   - Function names from `functions_definition.json` are tokenized and inserted into a Trie in `src/core/Trie.py`.
   - At generation time, the model is not allowed to emit arbitrary next tokens: only tokens that continue a valid function-name path in the Trie are permitted.

7. **Constrained decoding flow**
   - The system builds a function-selection prompt from `prompts/func_prompt.txt`.
   - That prompt includes the user request and the available function list.
   - The engine then performs greedy decoding over model logits, but only among tokens allowed by the current Trie node.
   - Once a terminal Trie node is reached, the decoded token sequence resolves to the selected function name.

8. **Argument extraction subsystem**
   - After function selection, the engine creates a second prompt describing the chosen function and its parameter schema.
   - Argument generation is type-aware:
     - numbers get restricted token sets,
     - booleans are constrained to `true`/`false`,
     - strings are decoded until a delimiter is hit.
   - This stage is separate from function selection because the constraints and stopping conditions differ by type.

9. **Prompt assets and separation of concerns**
   - `prompts/func_prompt.txt` contains the reusable instruction text for function selection.
   - Keeping prompts external to code makes the system easier to tune without changing orchestration logic.
   - The repo cleanly separates:
     - prompt templates,
     - validation,
     - constrained decoding,
     - and I/O.

10. **Data flow through the repository**
   - Input data lives under `data/input/`, including:
     - `functions_definition.json`
     - `function_calling_tests.json`
   - The engine consumes those files, produces structured predictions, and writes output JSON to a target path such as `data/output/function_calls.json`.
   - The output format is a compact record per prompt: original prompt, chosen function name, and parsed parameters.

11. **Important architectural dependency**
   - The system depends on **tokenization alignment** between:
     - the selected model’s tokenizer,
     - the Trie token sequences,
     - and the constrained argument decoders.
   - This is a key architectural boundary: if the tokenizer changes, the constraint logic must still match the same token IDs.

12. **Repository-level tooling**
   - `Makefile`, `pyproject.toml`, and `uv.lock` show the project is packaged for reproducible local execution.
   - `make install`, `make run`, `make debug`, and `make lint` are the main developer workflows.
   - This is an offline/local inference project rather than a service with networked runtime dependencies.

13. **What an architecture diagram should emphasize**
   - Draw the system as a pipeline with three major zones:
     - **CLI / file I/O**
     - **Core decoding engine**
     - **Local model runtime**
   - Inside the engine, show two sequential phases:
     - function-name selection via Trie-constrained decoding,
     - argument extraction via type-constrained generation.
   - Put `validators.py` as a gate before the engine, and `prompts/` and `data/input/` as external assets feeding it.

Main entry points: [`src/core/engine.py`](https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/engine.py) (Engine), [`src/core/validators.py`](https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/validators.py) (Validators), [`src/core/cli.py`](https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/cli.py) (CLI), [`src/core/Trie.py`](https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/Trie.py) (Trie)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_io["CLI / I/O"]
  node_main(("__main__<br/>entrypoint<br/>[__main__.py]"))
  node_cli["CLI<br/>parser<br/>[cli.py]"]
  node_writer["Result write<br/>output"]
end

subgraph group_core["Core engine"]
  node_validators["Validators<br/>schema gate<br/>[validators.py]"]
  node_engine["Engine<br/>orchestrator<br/>[engine.py]"]
  node_trie{{"Trie<br/>constraint index<br/>[Trie.py]"}}
  node_func_select(("Func select<br/>phase"))
  node_arg_extract(("Arg extract<br/>phase"))
  node_constrained_decode{{"Constrained decode<br/>decoder"}}
  node_prompt_build["Prompt build<br/>template step"]
end

subgraph group_runtime["Local model"]
  node_llm_sdk["LLM SDK<br/>model boundary<br/>[__init__.py]"]
  node_tokenizer(("Tokenizer<br/>token-id alignment"))
  node_logits(("Logits<br/>scoring"))
end

subgraph group_assets["Assets"]
  node_func_prompt["Function prompt<br/>template<br/>[func_prompt.txt]"]
  node_function_defs["Function catalog<br/>input json"]
  node_test_prompts["Test prompts<br/>input json"]
end

node_main -->|"start"| node_cli
node_cli -->|"validate"| node_validators
node_cli -->|"run"| node_engine
node_function_defs -->|"schema"| node_validators
node_test_prompts -->|"schema"| node_validators
node_validators -->|"clean inputs"| node_engine
node_engine -->|"assemble"| node_prompt_build
node_func_prompt -->|"template"| node_prompt_build
node_function_defs -->|"tokenize"| node_trie
node_trie -->|"allow tokens"| node_func_select
node_prompt_build -->|"selection prompt"| node_func_select
node_func_select -->|"decode"| node_constrained_decode
node_constrained_decode -->|"scores"| node_llm_sdk
node_llm_sdk -->|"token ids"| node_tokenizer
node_tokenizer -->|"align"| node_trie
node_func_select -->|"selected function"| node_arg_extract
node_prompt_build -->|"arg prompt"| node_arg_extract
node_arg_extract -->|"type constraints"| node_constrained_decode
node_constrained_decode -->|"score"| node_logits
node_engine -->|"emit"| node_writer
node_writer -.->|"done"| node_main

click node_main "https://github.com/roy-alpha/call-me-maybe/blob/main/src/__main__.py"
click node_cli "https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/cli.py"
click node_validators "https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/validators.py"
click node_engine "https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/engine.py"
click node_trie "https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/Trie.py"
click node_llm_sdk "https://github.com/roy-alpha/call-me-maybe/blob/main/llm_sdk/__init__.py"
click node_func_prompt "https://github.com/roy-alpha/call-me-maybe/blob/main/prompts/func_prompt.txt"
click node_function_defs "https://github.com/roy-alpha/call-me-maybe/blob/main/data/input/functions_definition.json"
click node_test_prompts "https://github.com/roy-alpha/call-me-maybe/blob/main/data/input/function_calling_tests.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_writer toneBlue
class node_validators,node_engine,node_trie,node_func_select,node_arg_extract,node_constrained_decode,node_prompt_build toneAmber
class node_llm_sdk,node_tokenizer,node_logits toneMint
class node_func_prompt,node_function_defs,node_test_prompts toneRose
```

## Components

### CLI / I/O

Command entry and file boundaries

- [__main__](https://github.com/roy-alpha/call-me-maybe/blob/main/src/__main__.py): entrypoint · Starts the CLI flow · `src/__main__.py`
- [CLI](https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/cli.py): parser · Reads paths and dispatches work · `src/core/cli.py`
- **Result write**: output · Serializes structured predictions to JSON

### Core engine

Validation, orchestration, and constrained decoding

- [Validators](https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/validators.py): schema gate · Checks function and prompt input structure · `src/core/validators.py`
- [Engine](https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/engine.py): orchestrator · Coordinates loading, decoding, and output · `src/core/engine.py`
- [Trie](https://github.com/roy-alpha/call-me-maybe/blob/main/src/core/Trie.py): constraint index · Stores tokenized function-name paths · `src/core/Trie.py`
- **Func select**: phase · Chooses one function under token constraints
- **Arg extract**: phase · Generates typed arguments for the selected function
- **Constrained decode**: decoder · Filters next tokens by allowed sets and stop rules
- **Prompt build**: template step · Assembles selection and argument prompts

### Local model

Tokenizer and logits boundary for local inference

- [LLM SDK](https://github.com/roy-alpha/call-me-maybe/blob/main/llm_sdk/__init__.py): model boundary · Abstracts local model and tokenizer access · `llm_sdk/__init__.py`
- **Tokenizer**: token-id alignment · Shared tokenization contract for trie and decoders
- **Logits**: scoring · Provides next-token scores for greedy decoding

### Assets

Prompt and input data files

- [Function prompt](https://github.com/roy-alpha/call-me-maybe/blob/main/prompts/func_prompt.txt): template · Reusable instruction text for function selection · `prompts/func_prompt.txt`
- [Function catalog](https://github.com/roy-alpha/call-me-maybe/blob/main/data/input/functions_definition.json): input json · Function names and parameter schemas · `data/input/functions_definition.json`
- [Test prompts](https://github.com/roy-alpha/call-me-maybe/blob/main/data/input/function_calling_tests.json): input json · Prompt cases used by the pipeline · `data/input/function_calling_tests.json`

## Connections

- __main__ → CLI: start · CLI entrypoint hands off to command parsing
- CLI → Validators: validate · Checks input files and JSON shape before execution
- CLI → Engine: run · Passes parsed paths and options into the coordinator
- Function catalog → Validators: schema · Function catalog is validated before use
- Test prompts → Validators: schema · Prompt/test input is validated before use
- Validators → Engine: clean inputs · Validated structures feed the orchestration layer
- Engine → Prompt build: assemble · Builds prompts for selection and argument generation
- Function prompt → Prompt build: template · Provides reusable instruction text
- Function catalog → Trie: tokenize · Function names are converted into token paths
- Trie → Func select: allow tokens · Constrains which function-name tokens can be emitted
- Prompt build → Func select: selection prompt · Feeds the function-choice decoding stage
- Func select → Constrained decode: decode · Greedy decoding runs under trie constraints
- Constrained decode → LLM SDK: scores · Uses model logits for next-token choice
- LLM SDK → Tokenizer: token ids · Tokenizer alignment is required for constraints
- Tokenizer → Trie: align · Trie paths and token IDs must match
- Func select → Arg extract: selected function · Chosen function becomes the argument-generation target
- Prompt build → Arg extract: arg prompt · Builds a second prompt from the chosen function schema
- Arg extract → Constrained decode: type constraints · Applies number, boolean, and string stopping rules
- Constrained decode → Logits: score · Reads model scores during argument generation
- Engine → Result write: emit · Writes structured predictions to the target output
- Result write → __main__: done · Completion returns control to the top level
