How cosmosshadow/generalagent works
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