Loop GPT

Implements a core Agent class that coordinates language models, memory systems, and tool execution through a defined state machine lifecycle (initialization → planning → tool execution → reflection → completion). The agent maintains internal state including goals, constraints, and conversation history, orchestrating multi-step task decomposition and execution loops without requiring external orchestration frameworks. State transitions are driven by LLM reasoning outputs parsed into structured action directives.

Provides complete agent state persistence including agent configuration, conversation history, memory contents, and tool states, enabling pause-and-resume workflows without external databases. Serialization captures the entire execution context (goals, constraints, LLM choice, embedding provider) and conversation transcript, allowing agents to be checkpointed mid-execution and restored to continue from the exact point of interruption. Uses Python pickle and JSON serialization with custom handlers for non-serializable objects.

Provides a Dockerfile and container configuration for running LoopGPT agents in isolated Docker containers. The container includes all dependencies, the LoopGPT framework, and a configured agent, enabling reproducible execution across environments. Supports volume mounting for persistent state and configuration, environment variable injection for API credentials, and network isolation. Enables agents to run in CI/CD pipelines, cloud platforms, and multi-tenant environments without dependency conflicts.

Enables agents to switch between multiple language models (OpenAI, open-source, custom) based on cost, latency, or capability requirements. The system supports fallback chains where if one model fails or is unavailable, the agent automatically tries the next model in the chain. Model selection can be dynamic based on task complexity or static based on configuration. Supports model-specific prompt optimization to maintain quality across different model families.

Provides tools enabling agents to create and delegate tasks to sub-agents, implementing hierarchical task decomposition. Agents can spawn child agents with specific goals and constraints, monitor their execution, and aggregate results. The system manages agent lifecycle (creation, execution, cleanup) and enables communication between parent and child agents through shared memory and result passing. Enables complex multi-agent workflows without external orchestration.

Defines a BaseModel interface that abstracts language model interactions, enabling swappable implementations for OpenAI (GPT-3.5, GPT-4), open-source models (via Ollama, HuggingFace), and custom providers. The abstraction handles prompt formatting, token counting, and response parsing, allowing agents to switch models without code changes. Includes optimized prompts for GPT-3.5 to minimize token overhead while maintaining reasoning quality, and supports both chat and completion APIs.

Provides a pluggable tool registry where tools are defined as Python classes inheriting from a BaseTool interface, with automatic schema extraction for LLM function calling. Tools are organized hierarchically (web tools, code execution tools, agent management tools) and expose a standardized execute() method. The system automatically generates JSON schemas from tool signatures and passes them to the LLM for structured action generation, enabling the agent to invoke tools with validated parameters without manual prompt engineering.

Implements an embedding-based memory system that stores agent interactions and retrieved information as vector embeddings, enabling semantic search and context-aware retrieval. The system uses a pluggable embedding provider (OpenAI embeddings, open-source models) to convert text to vectors, stores them in an in-memory vector store, and retrieves relevant context based on semantic similarity. Memory is integrated into the agent's prompt context, allowing the agent to reference past interactions and learned information without explicit recall instructions.

Provides a suite of web tools enabling agents to browse the internet, search for information, and interact with web pages. Tools include web search (via external APIs), page scraping, link extraction, and form interaction. The system abstracts browser automation details, allowing agents to request web information through natural language instructions that are translated into tool calls. Results are parsed and formatted for agent consumption, handling HTML parsing, text extraction, and error cases.

Provides tools for agents to execute Python code, manage files, and interact with the file system in a sandboxed manner. Includes code execution with output capture, file read/write operations, directory traversal, and command execution. The system enforces safety constraints (e.g., preventing access to sensitive directories) and captures execution results including stdout, stderr, and return values. Code execution results are formatted for agent consumption, enabling agents to test hypotheses and verify solutions.

Enables human operators to provide feedback and corrections during agent execution, allowing course correction when the agent deviates from intended goals. The system pauses execution at defined checkpoints, presents the agent's current state and proposed actions to the human, and accepts feedback that is incorporated into the agent's memory and future decision-making. Feedback is stored in the agent's memory system for learning across multiple interactions.

Provides a CLI interface for running agents directly from the terminal without writing Python code. The CLI accepts agent configuration (goals, model choice, tools to enable) as command-line arguments or interactive prompts, executes the agent, and displays results in human-readable format. Supports both one-shot execution and interactive mode where users can provide feedback and corrections during execution. The CLI is built on top of the Python API, enabling full customization through configuration files.

Provides an @aifunc decorator that transforms regular Python functions into LLM-augmented versions. Decorated functions are executed by the LLM with access to the original function's implementation as a reference, enabling the LLM to generate improved or alternative implementations. The decorator handles function signature extraction, LLM invocation, and result validation, allowing developers to enhance functions with AI reasoning without rewriting them. Results are cached to avoid redundant LLM calls.