DOCSEARCHbyAlgolia
Submit Docs

aipyapp

repository·main·Indexed 26 days ago

https://github.com/knownsec/aipyapp

An AI execution paradigm that replaces plugin-based agents with a direct Python-interpreter loop, allowing LLMs to interact with APIs, file systems, and browsers by writing and executing Python code. It provides a unified interface via the AiPy client, featuring multiple interaction modes including Task, Python, IPython, GUI, and an HTTP API server for n8n integration. The package includes a CLI for managing LLM providers, executing JSON tasks, and handling third-party library installations.

Tokens
35.8K
Snippets
57
Records
233
Agent score
88%

What's inside aipyapp

  1. Overview of the Python-Use Paradigm

    main

    Python-Use (Agent 2.0) is a task-oriented execution paradigm that combines Large Language Models (LLMs) with a Python interpreter. Unlike traditional 'prosthetic' AI agents that rely on external tools, function calling, or MCP servers, Python-Use uses code as the primary mechanism for action.

    Core Concept: No Agents, Code is Agent Instead of configuring complex workflows or plugin ecosystems, the model directly writes and executes Python code to interact with the environment. This allows the model to perform:

    • Data Analysis: Operating and analyzing data.
    • Browser Automation: Controlling web browsers.
    • System Control: Managing file systems and local environments.
    • IoT/Integration: Interacting with devices and system integrations.
    • Universal Capability: Using the Python ecosystem to reach 'anything'.

    The Execution Loop (AI ThinkDo):

    1. Task: User provides intent in natural language.
    2. Plan: Model decomposes and plans the execution path.
    3. Code: Model generates the optimal Python solution.
    4. Execute: Model interacts directly with the real environment.
    5. Feedback: Model receives results, analyzes deviations, and automatically adjusts.

  2. Overview of AIPy (Python-use)

    main
    AIPy is an implementation of the 'Python-use' paradigm. Instead of defining specific tool interfaces for an LLM, AIPy provides the LLM with a full Python execution environment. This allows the LLM to act like a user sitting at a computer, typing commands into a Python interpreter, observing results, and iterating. It is designed to automate complex data engineering tasks (cleaning, transforming, aggregating, visualizing) by allowing users to describe requirements in natural language rather than manually writing and running code.

  4. Review Risk Disclaimer for AI-Generated Code

    main

    The aipyapp program generates and executes code automatically via Large Language Models (LLMs). Users must be aware of the following risks:

    • Code Risks: Automatically generated code may contain logical errors, performance issues, or unsafe operations (e.g., deleting files, accessing networks, or executing system commands).
    • Accuracy: The program does not guarantee the accuracy, completeness, or suitability of the generated code.
    • System Safety: Running generated code without thorough review may cause damage to your system, data, or privacy.

    Disclaimer: This program is provided for development and testing purposes only. Users assume all responsibility for consequences arising from the use of the program and the execution of its generated code.

  5. Understand Context Cleanup in AiPy

    main

    AiPy implements an automatic Context Cleanup feature to manage token consumption and performance during multi-round task execution.

    Purpose

    As tasks progress through multiple steps and rounds, the conversation history grows, leading to:

    • High Token Usage: Intermediate errors, debug outputs, and temporary code blocks consume excessive tokens.
    • Redundancy: Previous error messages become useless once a fix is applied.
    • Performance Degradation: Long contexts slow down LLM response times and accuracy.
    • Increased Costs: Unnecessary tokens increase API expenses.

    How it Works

    AiPy uses a Step-level post-cleanup strategy. Instead of cleaning messages in real-time (which could interfere with the execution flow), cleanup occurs after a Step is completed but before the step_completed event is emitted. This ensures that error messages remain available for debugging until the step is actually finished.

    Cleanup Principles

    • Retain: System messages (system prompts), the user's initial_instruction, and the LLM's final_response.
    • Discard: All intermediate messages, including incorrect LLM responses, tool execution results, error feedback, debug info, and intermediate code blocks.

  6. Generate a survey using JSON to collect information

    main

    When a user's task requires essential information that cannot be reasonably assumed (e.g., high-risk decisions, budget constraints, or incomparable architectural choices), you can return a JSON-formatted survey to collect this data.

    Core Principles:

    • Minimize disruption: Only ask when necessary.
    • Prefer assumptions: If a low-risk assumption can be made, state it and proceed. If medium risk, provide a default + alternatives. Only return a survey for high-risk scenarios where assumptions are impossible.
    • Consolidate: Include all necessary questions in a single survey rather than sending multiple consecutive surveys.
    • Limit frequency: Aim for a maximum of 2-3 survey rounds throughout the entire conversation.

    Survey Delivery Format: Return the survey within a markdown code block named survey.

  7. Execute code blocks in TASK and MAIN modes

    main

    Custom commands can execute code blocks, but the behavior depends on the mode:

    TASK Mode Execution

    • Executes the code block and captures the output.
    • Default behavior: Only the execution result is sent to the AI (the source code is omitted to save tokens).
    • Use case: Data collection or state checking for AI analysis.

    MAIN Mode Execution

    • Executes the code block directly and displays the result in the terminal.
    • Use case: System operations and tool execution.

    Supported Code Block Types

    • python: Python code execution.
    • bash / shell: Shell commands.
    • exec: Direct execution.

    Testing Commands Locally

    Use the --local flag to preview command output without sending it to the LLM:

    /command_name --arg value --local

  8. Install MCP environment and tools

    main

    To use the Model Context Protocol (MCP) in aipyapp, you need a base environment and specific tool dependencies depending on the server type.

    Base Requirements

    • Node.js: Required for most MCP tools.
    • uv/uvx: Recommended for Python-based MCP tools. Install via pip install uv.

    Specific Tool Installation

    Node.js based tools:

    # Filesystem tool
npm install -g @modelcontextprotocol/server-filesystem

# Playwright tool
npm install -g @playwright/mcp

    Python based tools: Use uvx to run Python MCP servers. uvx handles dependencies automatically, so you typically don't need to install them separately.

    npm install -g @modelcontextprotocol/server-filesystem
npm install -g @playwright/mcp
pip install uv

  9. Manage configuration using Dynaconf pattern

    main

    The project uses a dual-configuration strategy to simplify management and protect sensitive data:

    • Default Configuration (default.toml): Contains standard settings and is committed to version control (Git).
    • Local Configuration: Used for user-specific, sensitive settings such as API KEYs. This should be kept separate from the default configuration to avoid leaking credentials.

  10. Use PromptFeatures to control template content

    main
    The PromptFeatures system allows you to conditionally include or exclude parts of a prompt template using a configuration-driven approach. You can control features via Python arguments or by defining a [features] section in your role's TOML configuration file. This is useful for creating different modes like 'minimal' or 'debug' without changing the underlying prompt logic.

  11. Use AiPy as the Unified Entry Point

    main

    Python-Use eliminates the need for complex clients or multiple agent plugins. The single entry point for all interactions is AiPy, which operates within a Python environment.

    To use the system, you interact through the unified terminal provided by AiPy, which serves as the bridge between your natural language intent and the Python interpreter execution loop.

  12. Use AiPy as the single entry point

    main

    Instead of using multiple AI applications or UI wrappers, you interact with the system through AiPy, a Python-powered AI client. It provides a unified interface where all interactions occur via Python, eliminating the need for plugin management or bloated clients.

    https://www.aipy.app/