# biubiutomato/tme-agent architecture

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

- Interactive diagram: https://gitdiagram.com/biubiutomato/tme-agent
- Repository: https://github.com/biubiutomato/tme-agent

## Overview

##### Project Type and Purpose
- This is an open-source research prototype called **Task Memory Engine (TME)**.
- It implements two conceptually related but structurally distinct versions:
- **v1**: Tree + graph memory framework with slot-based task tracking.
- **v2**: Spatial memory system with DAG dependencies and memory-aware QA.
- The goal is to enable multi-step LLM-based agents to plan tasks, roll back or replace subtasks, and perform graph-based reasoning.

##### File Structure
- Top level
- `run_case.py` – driver that reads a JSON case and invokes TME.
- `cases/` – JSON files defining user instruction sequences.
- `.env.example` – sample OpenAI API key config.
- `v1/` – version 1 modules and examples.
- `v2/` – version 2 modules.
- v1 directory
- `executor.py` – orchestrates LLM calls & memory updates.
- `memory_tree.py` – builds and maintains a hierarchical TaskMemoryTree.
- `reasoning.py` – graph-aware extensions & TRIM-like logic.
- `example/` – sample form-filling scripts.
- v2 directory
- `TaskMemoryStructure.py` – spatial memory & DAG data structures.
- `input_splitter.py` – LLM-based instruction decomposer.
- `intent_classifier_general.py` – default intent classifier.
- `intent_classifier_specific/` – specialized classifiers (e.g., `cart`).
- `trim.py` – Task Relation Inference Module.

##### Pull Key Insights from README
- **Pipeline Stages**: input parsing → decomposition → intent classification → memory update (tree or DAG) → rollback/replace support → memory-aware QA.
- **External Dependency**: OpenAI API (ChatGPT-4o model).
- **Test Harness**: `run_case.py` uses JSON cases, can switch between “general” vs “cart” modes.

a. Main Components
- **Test Runner**
- `run_case.py`
- `cases/*.json`
- **Core Pipeline**
1. Input Handler
2. Instruction Decomposer
- v1: `reasoning.py`
- v2: `input_splitter.py`
3. Intent Classifier
- General: `intent_classifier_general.py`
- Specific: `intent_classifier_specific/intent_classifier_cart.py`
4. Task Relation Inference (TRIM)
- v1: part of `reasoning.py`
- v2: `trim.py`
5. Memory Structure
- v1: `memory_tree.py` (TaskMemoryTree)
- v2: `TaskMemoryStructure.py` (spatial DAG)
6. Executor / Orchestrator
- v1: `executor.py`
- v2: orchestration code within `run_case.py` + module imports
7. Memory-Aware QA Module (final query stage)
- **External Services**
- OpenAI API
- **Configuration & Utilities**
- `.env` variables via `python-dotenv`
- Logging, error handling

b. Relationships & Data Flow
1. **run_case.py** reads a JSON case → identifies mode (general/cart) → loops through instructions.
2. Each instruction feeds into the **Core Pipeline**:
→ **Decomposer** breaks into substeps → **Intent Classifier** assigns relation type → **TRIM** refines dependencies → **Memory Structure** applies update/rollback → store updated memory.
3. **Executor** issues LLM calls (OpenAI API) at decomposer and QA stages.
4. **Memory-Aware QA** reads the in-memory graph/tree → forms final answer.
5. Results (updated memory state or QA output) are logged or printed.

c. Architectural Patterns & Principles
- **Modular Pipeline**: clear separation of concerns (decomposer, classifier, memory, QA).
- **Graph & Tree Memory**: v1 blends hierarchical and graph, v2 uses pure spatial/DAG.
- **Externalized LLM Integration**: all language reasoning via OpenAI API, isolated behind modules.

d. Key Technologies
- Python 3.x
- OpenAI Python SDK
- python-dotenv
- JSON test data

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level Orchestration
    runCase["run_case.py"]:::orchestrator
    cases["cases/*.json"]:::orchestrator
    runCase --> cases
    runCase -->|selects mode| v1Start
    runCase -->|selects mode| v2Start

    %% v1 Pipeline
    subgraph "v1 Pipeline"
        v1Start["v1 mode"]:::orchestrator
        executor["executor.py"]:::orchestrator
        reasoning["reasoning.py"]:::pipeline
        memoryTree["memory_tree.py"]:::memory
        exampleDir["example/"]:::orchestrator
        figsV1["figs/"]:::orchestrator
        v1Start --> reasoning
        reasoning --> executor
        executor --> memoryTree
        memoryTree --> executor
        executor --> exampleDir
        executor --> figsV1
    end

    %% v2 Pipeline
    subgraph "v2 Pipeline"
        v2Start["v2 mode"]:::orchestrator
        splitter["input_splitter.py"]:::pipeline
        intentGen["intent_classifier_general.py"]:::pipeline
        intentCart["intent_classifier_specific/intent_classifier_cart.py"]:::pipeline
        trim["trim.py"]:::pipeline
        dag["TaskMemoryStructure.py"]:::memory
        figsV2["figs/"]:::orchestrator
        v2Start --> splitter
        splitter --> intentGen
        splitter --> intentCart
        intentGen --> trim
        intentCart --> trim
        trim --> dag
        dag --> trim
        trim --> figsV2
    end

    %% Loop per Instruction
    reasoning -->|"LLM call"| openAI
    splitter -->|"LLM call"| openAI
    memoryTree -->|"rollback/replace"| memoryTree
    dag -->|"rollback/replace"| dag

    %% Memory-Aware QA
    QA["Memory-Aware QA Module"]:::pipeline
    memoryTree --> QA
    dag --> QA
    QA -->|"final LLM query"| openAI

    %% External Services & Config
    openAI["OpenAI API"]:::external
    env[".env.example"]:::config
    runCase --> env

    %% Click Events
    click runCase "https://github.com/biubiutomato/tme-agent/blob/main/run_case.py"
    click cases "https://github.com/biubiutomato/tme-agent/tree/main/cases/"
    click env "https://github.com/biubiutomato/tme-agent/blob/main/.env.example"
    click executor "https://github.com/biubiutomato/tme-agent/blob/main/v1/executor.py"
    click reasoning "https://github.com/biubiutomato/tme-agent/blob/main/v1/reasoning.py"
    click memoryTree "https://github.com/biubiutomato/tme-agent/blob/main/v1/memory_tree.py"
    click exampleDir "https://github.com/biubiutomato/tme-agent/tree/main/v1/example/"
    click figsV1 "https://github.com/biubiutomato/tme-agent/tree/main/v1/figs/"
    click splitter "https://github.com/biubiutomato/tme-agent/blob/main/v2/input_splitter.py"
    click intentGen "https://github.com/biubiutomato/tme-agent/blob/main/v2/intent_classifier_general.py"
    click intentCart "https://github.com/biubiutomato/tme-agent/blob/main/v2/intent_classifier_specific/intent_classifier_cart.py"
    click trim "https://github.com/biubiutomato/tme-agent/blob/main/v2/trim.py"
    click dag "https://github.com/biubiutomato/tme-agent/blob/main/v2/TaskMemoryStructure.py"
    click figsV2 "https://github.com/biubiutomato/tme-agent/tree/main/v2/figs/"

    %% Styles
    classDef orchestrator fill:#cce5ff,stroke:#004085,color:#004085;
    classDef pipeline fill:#d4edda,stroke:#155724,color:#155724;
    classDef memory fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e0ccff,stroke:#4b0082,color:#4b0082;
    classDef config fill:#f8f9fa,stroke:#6c757d,color:#6c757d;
```
