# jaybea/o1agenticplanner architecture

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

- Interactive diagram: https://gitdiagram.com/jaybea/o1agenticplanner
- Repository: https://github.com/jaybea/o1agenticplanner

## Overview

##### Project type and purpose
- This is a Python-based, educational command-line tool/library for exploring AI-driven order-fulfillment automation.
- It demonstrates a two-stage AI pipeline (planning with O1-mini and execution with GPT-4), configurable business contexts, scenarios, and pluggable business functions.

##### File structure
- Top-level files: .env.example, requirements.txt, README.md, LICENSE → configuration, dependency, and documentation.
- src/order_fulfillment: the main package
- config.py → environment and model settings loader
- context.py → business context definitions (inventory, capacity, etc.)
- scenarios.py → predefined test scenarios
- plans.py → plan representation and storage
- executor.py → orchestration of planning + execution pipeline
- functions.py + helper.py + utils.py → business-function implementations and utilities
- registry.py → registry pattern for models, contexts, functions, scenarios
- main.py → CLI entry point
- src/prototype: sandboxed or earlier proof-of-concept versions of similar modules

##### Key insights from the README
- Separation of “planning” and “execution” phases
- Swappable AI models and contexts
- Educational emphasis: learn clean structure, type hints, testing AI logic

##### Main components
a. User / CLI (main.py)
b. Configuration Loader (config.py)
c. Registry Service (registry.py)
d. Context Manager (context.py + scenarios.py)
e. Planner Service (plans.py + functions to call O1-mini model)
f. Executor Service (executor.py + calls to GPT-4 + business functions in functions.py)
g. Business Function Library (functions.py + helper.py + utils.py)
h. Plan Store or Cache (persistent plan storage in plans.py)
i. External AI APIs (O1-mini endpoint, OpenAI GPT-4)
j. Virtual environment and environment variables (.env)

##### Relationships and interactions
- CLI invokes Configuration Loader → Registry Service
- Registry wires up Context Manager & Scenario definitions
- CLI triggers Executor Service:
- Executor requests a plan from Planner Service (via AI model)
- Plan is stored in Plan Store
- Executor retrieves plan → executes step-by-step using Business Function Library, driving calls to GPT-4 or local logic
- Context Manager provides current business state to both Planner and Executor
- All AI calls pass through well-defined interfaces in executor.py and plans.py

##### Architectural patterns and design principles
- Separation of concerns: planning vs. execution, context vs. functions
- Registry pattern for plug-and-play components (models, contexts, scenarios, functions)
- Pipeline/orchestration pattern in executor.py
- Config-driven behavior (env vars + config.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external
    User -->|"runs CLI"| CLI

    %% Package Boundary
    subgraph "src/order_fulfillment" 
        direction TB

        CLI["CLI Entry (main.py)"]:::core
        Config["Config Loader (config.py)"]:::config
        Registry["Registry Service (registry.py)"]:::core
        Context["Context Manager (context.py)"]:::core
        Scenarios["Scenario Definitions (scenarios.py)"]:::core
        Planner["Planner Service (plans.py)"]:::core
        Executor["Executor Service (executor.py)"]:::core
        FunctionsLib["Business Function Library\n(functions.py, helper.py, utils.py)"]:::core
        PlanStore["Plan Store / Cache (plans.py)"]:::datastore

        CLI -->|"load settings"| Config
        CLI -->|"initialize registry"| Registry
        Registry -->|"register contexts"| Context
        Registry -->|"register scenarios"| Scenarios

        CLI -->|"start pipeline"| Executor
        Executor -->|"request plan"| Planner
        Planner -->|"AI prompt → plan"| O1AI
        Planner -->|"store plan"| PlanStore
        Executor -->|"retrieve plan"| PlanStore
        Executor -->|"execution steps"| FunctionsLib
        Executor -->|"call GPT-4"| GPT4AI
        Context -->|"provide context data"| Planner
        Context -->|"provide context data"| Executor
        Scenarios -->|"provide scenario data"| Context
    end

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        O1AI["O1-mini AI"]:::external
        GPT4AI["OpenAI GPT-4"]:::external
    end

    %% Environment & Docs
    Env[".env (env vars)"]:::config
    Docs["requirements.txt\nREADME.md\nLICENSE"]:::config

    User -->|"sets API keys"| Env
    User -->|"views docs"| Docs

    %% Click events
    click CLI "https://github.com/jaybea/o1agenticplanner/blob/main/src/order_fulfillment/main.py"
    click Config "https://github.com/jaybea/o1agenticplanner/blob/main/src/order_fulfillment/config.py"
    click Registry "https://github.com/jaybea/o1agenticplanner/blob/main/src/order_fulfillment/registry.py"
    click Context "https://github.com/jaybea/o1agenticplanner/blob/main/src/order_fulfillment/context.py"
    click Scenarios "https://github.com/jaybea/o1agenticplanner/blob/main/src/order_fulfillment/scenarios.py"
    click Planner "https://github.com/jaybea/o1agenticplanner/blob/main/src/order_fulfillment/plans.py"
    click Executor "https://github.com/jaybea/o1agenticplanner/blob/main/src/order_fulfillment/executor.py"
    click FunctionsLib "https://github.com/jaybea/o1agenticplanner/blob/main/src/order_fulfillment/functions.py"
    click PlanStore "https://github.com/jaybea/o1agenticplanner/blob/main/src/order_fulfillment/plans.py"
    click Env "https://github.com/jaybea/o1agenticplanner/blob/main/.env.example"
    click Docs "https://github.com/jaybea/o1agenticplanner/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef external fill:#bbf,stroke:#333,stroke-width:1px
    classDef datastore fill:#bfb,stroke:#333,stroke-width:1px
    classDef config fill:#fbf,stroke:#333,stroke-width:1px
```
