# cosmosshadow/generalagent architecture

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

- Interactive diagram: https://gitdiagram.com/cosmosshadow/generalagent
- Repository: https://github.com/cosmosshadow/generalagent

## Overview

##### Project Type and Purpose
- This is a Python-native Agent framework (GeneralAgent) that bridges large language models (LLMs) and Python.
- It isn’t a web or mobile app, but a library that:
- Wraps LLM calls (OpenAI, Azure, OneAPI, custom)
- Parses LLM responses into actions (code execution, shell commands, knowledge lookups)
- Maintains state/memory and serializes it
- Exposes an API (Agent.run, Agent.user_input, etc.) for driving complex, multi-step flows

##### High-Level File Structure
- GeneralAgent/agent – core Agent class and orchestration logic
- GeneralAgent/interpreter – pluggable interpreters (Python, Shell, Knowledge, Role, AppleScript)
- GeneralAgent/memory – memory implementations (stack/normal)
- GeneralAgent/skills – tool-call wrappers (OpenAIModel, file ops, web tools, embeddings, unique names, token counts, python envs)
- GeneralAgent/llamaindex.py – (optional) integration with LlamaIndex for knowledge
- GeneralAgent/utils.py – supporting utilities
- examples/ – usage scenarios
- docs/ – design paper and developer guides
- test/ – unit tests validating modules

##### Key Components
a. Agent Core
- Orchestrates the loop: receive user input → build messages → call LLM → parse JSON or code → dispatch to interpreters/skills → update memory → return result.
b. Interpreters
- PythonInterpreter: executes Python snippets, captures state
- ShellInterpreter: runs shell commands
- KnowledgeInterpreter: retrieves from vector stores or PDFs
- RoleInterpreter & AppleScriptInterpreter: specialized interpreters
c. Memory
- NormalMemory: conversation history, stack memory for self-calls
- Disk persistence: workspace folder serializes messages & interpreter state
d. Skills
- llm_inference: delegates to OpenAI SDK or custom function
- embedding_texts: builds embeddings for knowledge
- file_operation, web_tools: I/O and web integration
- token_count, unique_name, python_envs: auxiliary
e. External Services & Resources
- LLM APIs (OpenAI, Azure, OneAPI, custom)
- File system (knowledge PDFs, serialized state)
- OS shell, Python runtime
- (Optional) LlamaIndex vector store

##### Relationships and Data Flows
- User → Agent.user_input/run → Agent Core
- Agent Core → llm_inference (Skill) → LLM API → Agent Core
- Agent Core → Parser → selects Interpreter(s) or Skill(s)
- Interpreter(s) ↔ Python runtime or Shell or Knowledge store
- Results → Memory (NormalMemory)
- Memory → Agent Core for context on next turn
- On workspace configured: Memory & Interpreter state → disk (serialization)

##### Architectural Patterns and Principles
- Modular layering: Core, Interpreters, Skills, Memory
- Strategy pattern: interchangeable interpreter and skill implementations
- Dependency injection: custom llm_inference, embedding_texts, interpreter overrides
- Serialization for reproducibility: stateful restart of agents

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Inputs
    User["User"]:::external
    KnowledgeFiles["Knowledge Files"]:::external

    %% External Services
    LLMAPI["LLM API\n(OpenAI/Azure/OneAPI)"]:::external
    PythonRuntime["Python Runtime"]:::external
    OSShell["OS Shell"]:::external

    %% Core
    subgraph "Agent Core"
        direction TB
        AgentCore["Agent Core\nGeneralAgent/agent/agent.py"]:::core
        Parser["Parser"]:::core
    end

    %% Interpreters
    subgraph "Interpreters"
        direction TB
        PythonInterp["PythonInterpreter\npython_interpreter.py"]:::core
        ShellInterp["ShellInterpreter\nshell_interpreter.py"]:::core
        KnowledgeInterp["KnowledgeInterpreter\nknowledge_interpreter.py"]:::core
        RoleInterp["RoleInterpreter\nrole_interpreter.py"]:::core
        AppleScriptInterp["AppleScriptInterpreter\napplescript_interpreter.py"]:::core
    end

    %% Skills
    subgraph "Skills"
        direction TB
        LLMInference["LLM Inference\nopenai_model.py"]:::skill
        FileOps["FileOperations\nfile_operation.py"]:::skill
        WebTools["WebTools\nweb_tools.py"]:::skill
        PythonEnvs["PythonEnvs Helper\npython_envs.py"]:::skill
        TokenCount["TokenCount\ntoken_count.py"]:::skill
        UniqueName["UniqueName\nunique_name.py"]:::skill
    end

    %% Memory
    subgraph "Memory"
        direction TB
        NormalMemory["NormalMemory\nnormal_memory.py"]:::core
    end

    %% Utilities
    Utils["Utils\nutils.py"]:::core

    %% Workspace Storage
    Workspace["Workspace Storage\n(serialized state)"]:::storage

    %% Flows
    User -->|"Agent.user_input/run"| AgentCore
    AgentCore --> Parser
    Parser -->|dispatch to| PythonInterp
    Parser -->|dispatch to| ShellInterp
    Parser -->|dispatch to| KnowledgeInterp
    Parser -->|dispatch to| RoleInterp
    Parser -->|dispatch to| AppleScriptInterp

    AgentCore -->|calls skill| LLMInference
    AgentCore -->|uses| FileOps
    AgentCore -->|uses| WebTools
    AgentCore -->|uses| PythonEnvs
    AgentCore -->|uses| TokenCount
    AgentCore -->|uses| UniqueName

    LLMInference -->|API call| LLMAPI

    PythonInterp -->|executes code| PythonRuntime
    ShellInterp -->|runs commands| OSShell
    KnowledgeFiles -->|source| KnowledgeInterp

    %% Memory interactions
    AgentCore -->|reads/writes| NormalMemory
    PythonInterp -->|writes state| NormalMemory
    NormalMemory -->|persist| Workspace
    PythonInterp -->|serialize state| Workspace

    %% Click Events
    click AgentCore "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/agent/agent.py"
    click Parser "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/agent/__init__.py"
    click PythonInterp "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/interpreter/python_interpreter.py"
    click ShellInterp "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/interpreter/shell_interpreter.py"
    click KnowledgeInterp "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/interpreter/knowledge_interpreter.py"
    click RoleInterp "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/interpreter/role_interpreter.py"
    click AppleScriptInterp "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/interpreter/applescript_interpreter.py"
    click PythonInterp "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/interpreter/interpreter.py"
    click Utilities "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/utils.py"
    click NormalMemory "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/memory/normal_memory.py"
    click LLMInference "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/skills/openai_model.py"
    click FileOps "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/skills/file_operation.py"
    click WebTools "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/skills/web_tools.py"
    click PythonEnvs "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/skills/python_envs.py"
    click TokenCount "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/skills/token_count.py"
    click UniqueName "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/skills/unique_name.py"
    click Workspace "https://github.com/cosmosshadow/generalagent/blob/main/GeneralAgent/memory/__init__.py"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef skill fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef storage fill:#ffebcc,stroke:#333,stroke-width:1px
```
