Skip to content

JRF-2018/simplest-pal

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

14 Commits
LICENSE
LICENSE
 
 
README.md
README.md
 
 
example_1.py
example_1.py
 
 
example_2.py
example_2.py
 
 
example_3.py
example_3.py
 
 
setup.py
setup.py
 
 
simplest_pal.py
simplest_pal.py
 
 

Repository files navigation

simplest-pal: The Simplest PDB Automation Layer for AI-Driven Debugging

simplest-pal is the simplest implementation of an "AI" when wrapping PDB (Python Debugger) with an AI. This is a concept implementation, primarily intended to be used in conjunction with JRF-2018/jrf_pdb_agent_lib.

Overview

simplest-pal is a CLI tool that automates the PDB debugger during Python script execution, allowing for AI agent or human intervention under specific conditions.

  • pal.do(): Typically continues the PDB session (sends the c command). If current_code is None or PDB enters an input-waiting state, it transfers control to the debugger.

  • pal.consult_human(): Transfers control to the debugger when human intervention is required.

In principle, we'd want to hook the c (continue) command to return control to simplest-pal. However, the current implementation is such that pressing c only keeps the debugger screen visible without doing anything, and only when a string returned from pal.do() or pal.consult_human() appears in the output (after confirming it's ready for input, perhaps with a short wait), will it send commands like c.

It also includes functionality to save a complete log of the debugger session.

Features

  • AI-Wrapped Debugger: Provides a simple automation layer on top of PDB, enabling an AI agent to interact with the debugging process.

  • Concept Implementation: A proof-of-concept to demonstrate the basic workflow of AI-driven debugging.

  • Integration with JRF-2018/jrf_pdb_agent_lib: Designed to work in conjunction with jrf_pdb_agent_lib, but can also support other pdb_agent_lib implementations.

  • Log Storage: Saves a complete log of the debugger's input and output during the session.

  • CLI Interface: Provides a simple command-line interface implemented in Python.

  • .apy File Support: Can execute and debug Python scripts with the .apy extension. The .apy extension stands for AI Python or Agent Python, and is intended for code that is continuously modified or generated by an AI agent. It signifies a file designed to be executed by an AI-wrapped debugger like simplest-pal, rather than just a standard Python script.

  • No Security Considerations: As this is a concept implementation, security is not a primary concern.

Installation

This project can be installed from the repository.

pip install git+https://github.com/JRF-2018/simplest-pal

Usage

Run simplest-pal by specifying the Python script you want to debug.

simplest-pal your_script.py [script_args...]

  • your_script.py: Path to the Python script to be debugged.

  • [script_args...]: Arguments to pass to your_script.py.

Specifying PDB Log File

To specify the log file for the debugger session, use the --pal-log option.

simplest-pal --pal-log my_debug_session.log your_script.py

The default log file is pdb_session.log.

Automatic Quitting on Debugger Stop

To always q (quit) when the debugger stops without being able to c (continue), use the --pal-quit-on-stop option.

How It Works

simplest-pal intercepts PDB's input and output by hooking sys.stdin, sys.stdout, and sys.stderr.

  1. Starting a PDB Session: When the target script calls pdb.set_trace(), simplest-pal takes control and initiates a PDB session.

  2. Output Monitoring: It monitors the output from PDB, detecting specific keywords such as AI interaction points (e.g., "AI Interaction Point", "Current Code Context (for AI reference)") or human intervention requests (e.g., "Human Consultation Requested").

  3. Auto-Continuation: When these keywords are detected, simplest-pal automatically sends the c (continue) command to PDB, resuming script execution.

  4. Human Intervention: If PDB is waiting for user input (when the (Pdb) prompt is displayed) and auto-continuation conditions are not met, a human can directly enter PDB commands.

  5. Logging: All PDB input and output are recorded in the specified log file.

Design Considerations: Special Usage of textwrap.dedent (d_py, d_md)

It might be beneficial to use textwrap.dedent aliased as d_py or d_md for current_code and order within (jrf_)pdb_agent_lib.

If such libraries become widely used, it is conceivable that dedent would become a common practice for removing indentation from code or instruction strings.

In such a scenario, simply writing dedent might make it difficult for editors to recognize the content of the string (e.g., whether it's Python code or Markdown), potentially preventing proper syntax highlighting or other features from being applied. Therefore, by importing dedent with aliases like d_py (dedent Python) and d_md (dedent Markdown), the aliased function names themselves are intended to provide hints to the editor about the string's content. This aims to improve the readability of both AI-generated and user-written code, enhancing the overall development experience.

Usage Example

Name the following file example_1.py and run it with simplest-pal.

import jrf_pdb_agent_lib as pal
from textwrap import dedent as d_py
from textwrap import dedent as d_md

pal.login()

x = 42

r = pal.do(d_md("Do something good."),
           current_code = d_py("""\
               pal.do('Multiply 2',current_code='x=x*2')
               pal.do('Minus 1',current_code='x=x-1')
               pal.RESULT = x
           """))

print(r)

The output will be as follows.

$ simplest-pal example_1.py
Simplest P.A.L.: Running target script: 'example_1.py'
PDB Agent Lib: Initialized. Shared memory is used for IPC.

--- PDB Agent Lib: AI Interaction Point ---
Order for AI: 'Do something good.'
Current Code Context (for AI reference): "pal.do('Multiply 2',current_code='x=x*2')\npal.do('Minus 1',current_code='x=x-1')\npal.RESULT = x\n"
AI should interact directly via PDB commands or shared memory.
--- PDB Agent Lib: Entering Debugger ---
PDB Automation: Debugger session activated.
> /some/where/simplest_pal.py(204)set_trace_with_hooks()
-> pdb_auto.exit_debugger_hook()
(Pdb) PDB Automation (readline): Auto-continuing (AI interaction context detected).
PDB Automation: Debugger session deactivated.
--- PDB Agent Lib: Exiting Debugger ---
PDB Agent Lib: Executing code from AI: "pal.do('Multiply 2',current_code='x=x*2')\npal.do('Minus 1',current_code='x=x-1')\npal.RESULT = x\n"

--- PDB Agent Lib: AI Interaction Point ---
Order for AI: 'Multiply 2'
Current Code Context (for AI reference): 'x=x*2'
AI should interact directly via PDB commands or shared memory.
--- PDB Agent Lib: Entering Debugger ---
PDB Automation: Debugger session activated.
> /some/where/simplest_pal.py(204)set_trace_with_hooks()
-> pdb_auto.exit_debugger_hook()
(Pdb) PDB Automation (readline): Auto-continuing (AI interaction context detected).
PDB Automation: Debugger session deactivated.
--- PDB Agent Lib: Exiting Debugger ---
PDB Agent Lib: Executing code from AI: 'x=x*2'
PDB Agent Lib: AI-provided code execution successful.
--- PDB Agent Lib: Exiting AI Interaction ---
PDB Agent Lib: No result returned from AI.

--- PDB Agent Lib: AI Interaction Point ---
Order for AI: 'Minus 1'
Current Code Context (for AI reference): 'x=x-1'
AI should interact directly via PDB commands or shared memory.
--- PDB Agent Lib: Entering Debugger ---
PDB Automation: Debugger session activated.
> /some/where/simplest_pal.py(204)set_trace_with_hooks()
-> pdb_auto.exit_debugger_hook()
(Pdb) PDB Automation (readline): Auto-continuing (AI interaction context detected).
PDB Automation: Debugger session deactivated.
--- PDB Agent Lib: Exiting Debugger ---
PDB Agent Lib: Executing code from AI: 'x=x-1'
PDB Agent Lib: AI-provided code execution successful.
--- PDB Agent Lib: Exiting AI Interaction ---
PDB Agent Lib: No result returned from AI.
PDB Agent Lib: AI-provided code execution successful.
--- PDB Agent Lib: Exiting AI Interaction ---
PDB Agent Lib: Returning result from AI.
83
Simplest P.A.L.: Target script execution completed normally.

PDB session log saved to 'pdb_session.log'.

This means that c was automatically pressed three times.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

JRF ( http://jrf.cocolog-nifty.com/statuses , Twitter (X): @jion_rockford )

This project was largely generated by Gemini 2.5 Flash and Pro.

simplest-pal: AI駆動デバッグのための最もシンプルなPDB自動化レイヤー

simplest-palは、PDB（Python Debugger）を「AI」でラップする場合の「AI」の最もシンプルな実装です。これはコンセプトの実装であり、主にJRF-2018/jrf_pdb_agent_libと連携して使用することを想定しています。

概要

simplest-palは、Pythonスクリプトの実行中にPDBデバッガを自動化し、特定の条件下でAIエージェントまたは人間による介入を可能にするCLIツールです。

  • pal.do(): 通常はPDBセッションを継続（cコマンドを送信）します。current_codeがNoneの場合、またはPDBが入力待ち状態になった場合は、デバッガに制御を移します。

  • pal.consult_human(): 人間による介入が必要な場合にデバッガに制御を移します。

基本的には、c（continue）コマンドが入力されたことをフックしてsimplest-palに制御を戻したいところです。ただし、実際にはcが押されてもデバッガ画面を表示し続けるだけで何もせず、pal.do()やpal.consult_human()から返された文字列が出力に現れた場合（さらに入力可能になったことを確認した後）にのみ、cなどのコマンドを送信するという実装になっています。

デバッガセッションの完全なログを保存する機能も備えています。

特徴

  • AIラップデバッガ: PDBの上にシンプルな自動化レイヤーを提供し、AIエージェントがデバッグプロセスと対話できるようにします。

  • コンセプト実装: AI駆動デバッグの基本的なワークフローを示すための概念実証です。

  • JRF-2018/jrf_pdb_agent_libとの連携: jrf_pdb_agent_libと連携して動作するように設計されていますが、他のpdb_agent_libの実装にも対応可能です。

  • ログ保存: デバッガの入出力を含むセッション全体のログを保存します。

  • CLIインターフェース: Pythonで実装されたシンプルなコマンドラインインターフェースを提供します。

  • .apyファイル対応: .apy拡張子のPythonスクリプトも対象として実行・デバッグが可能です。.apy は AI Python または Agent Python の略として、AI エージェントが継続的に変更・生成していくコードを想定しています。これは単なるPythonコードではなく、simplest-palのようなAIラップデバッガによって実行されることを意図した拡張子です。

  • セキュリティの考慮なし: これはコンセプト実装であるため、セキュリティは考慮されていません。

インストール

このプロジェクトは、レポジトリからインストールできます。

pip install git+https://github.com/JRF-2018/simplest-pal

使い方

simplest-palは、デバッグしたいPythonスクリプトを指定して実行します。

simplest-pal your_script.py [script_args...]

  • your_script.py: デバッグしたいPythonスクリプトのパス。

  • [script_args...]: your_script.pyに渡す引数。

PDBログファイルの指定

デバッガセッションのログファイルを指定するには、--pal-logオプションを使用します。

simplest-pal --pal-log my_debug_session.log your_script.py

デフォルトのログファイルはpdb_session.logです。

デバッガ停止時の自動終了

c (continue) できずにデバッガに止まるとき、必ずq (quit)するには、--pal-quit-on-stopオプションを使用します。

動作原理

simplest-palは、sys.stdin、sys.stdout、sys.stderrをフックしてPDBの入出力をインターセプトします。

  1. PDBセッションの開始: 対象のスクリプトがpdb.set_trace()を呼び出すと、simplest-palが制御を奪い、PDBセッションを開始します。

  2. 出力の監視: PDBからの出力を監視し、AIとの対話ポイント（例: "AI Interaction Point"、"Current Code Context (for AI reference)"）や人間による介入リクエスト（例: "Human Consultation Requested"）などの特定のキーワードを検出します。

  3. 自動継続: これらのキーワードが検出された場合、simplest-palは自動的にPDBにc（continue）コマンドを送信し、スクリプトの実行を継続させます。

  4. 人間による介入: PDBがユーザー入力を待っている状態（(Pdb)プロンプトが表示された場合）で、自動継続の条件が満たされない場合は、人間が直接PDBコマンドを入力できるようになります。

  5. ログ記録: すべてのPDBの入出力は指定されたログファイルに記録されます。

設計上の考慮事項: textwrap.dedent の特別な使用法 (d_py, d_md)

(jrf_)pdb_agent_lib の current_code や order に textwrap.dedent を d_py または d_md として使用するとよいかもしれません。

もしこういったライブラリが広く使われるようになった場合、コードや指示の文字列からインデントを削除するために dedent を使うのが一般的になると考えられます。

このとき、ただ dedent とだけ記述すると、エディタがその文字列の内容（PythonコードなのかMarkdownなのか等）を認識しにくく、シンタックスハイライトなどの機能が適切に適用されない可能性があります。そこで、dedent を d_py (dedent Python) や d_md (dedent Markdown) のように別名でインポートし、これらを変名した関数名自体がエディタに対して文字列の内容に関するヒントを提供するように意図しています。これにより、AI生成コードやユーザーが記述するコードの可読性が向上し、開発体験がより良くなることを目指しています。

使用例

次のようなファイルを example_1.py と名付け simplest-pal から実行します。

import jrf_pdb_agent_lib as pal
from textwrap import dedent as d_py
from textwrap import dedent as d_md

pal.login()

x = 42

r = pal.do(d_md("Do something good."),
           current_code = d_py("""\
               pal.do('Multiply 2',current_code='x=x*2')
               pal.do('Minus 1',current_code='x=x-1')
               pal.RESULT = x
           """))

print(r)

次のような出力になります。

$ simplest-pal example_1.py
Simplest P.A.L.: Running target script: 'example_1.py'
PDB Agent Lib: Initialized. Shared memory is used for IPC.

--- PDB Agent Lib: AI Interaction Point ---
Order for AI: 'Do something good.'
Current Code Context (for AI reference): "pal.do('Multiply 2',current_code='x=x*2')\npal.do('Minus 1',current_code='x=x-1')\npal.RESULT = x\n"
AI should interact directly via PDB commands or shared memory.
--- PDB Agent Lib: Entering Debugger ---
PDB Automation: Debugger session activated.
> /some/where/simplest_pal.py(204)set_trace_with_hooks()
-> pdb_auto.exit_debugger_hook()
(Pdb) PDB Automation (readline): Auto-continuing (AI interaction context detected).
PDB Automation: Debugger session deactivated.
--- PDB Agent Lib: Exiting Debugger ---
PDB Agent Lib: Executing code from AI: "pal.do('Multiply 2',current_code='x=x*2')\npal.do('Minus 1',current_code='x=x-1')\npal.RESULT = x\n"

--- PDB Agent Lib: AI Interaction Point ---
Order for AI: 'Multiply 2'
Current Code Context (for AI reference): 'x=x*2'
AI should interact directly via PDB commands or shared memory.
--- PDB Agent Lib: Entering Debugger ---
PDB Automation: Debugger session activated.
> /some/where/simplest_pal.py(204)set_trace_with_hooks()
-> pdb_auto.exit_debugger_hook()
(Pdb) PDB Automation (readline): Auto-continuing (AI interaction context detected).
PDB Automation: Debugger session deactivated.
--- PDB Agent Lib: Exiting Debugger ---
PDB Agent Lib: Executing code from AI: 'x=x*2'
PDB Agent Lib: AI-provided code execution successful.
--- PDB Agent Lib: Exiting AI Interaction ---
PDB Agent Lib: No result returned from AI.

--- PDB Agent Lib: AI Interaction Point ---
Order for AI: 'Minus 1'
Current Code Context (for AI reference): 'x=x-1'
AI should interact directly via PDB commands or shared memory.
--- PDB Agent Lib: Entering Debugger ---
PDB Automation: Debugger session activated.
> /some/where/simplest_pal.py(204)set_trace_with_hooks()
-> pdb_auto.exit_debugger_hook()
(Pdb) PDB Automation (readline): Auto-continuing (AI interaction context detected).
PDB Automation: Debugger session deactivated.
--- PDB Agent Lib: Exiting Debugger ---
PDB Agent Lib: Executing code from AI: 'x=x-1'
PDB Agent Lib: AI-provided code execution successful.
--- PDB Agent Lib: Exiting AI Interaction ---
PDB Agent Lib: No result returned from AI.
PDB Agent Lib: AI-provided code execution successful.
--- PDB Agent Lib: Exiting AI Interaction ---
PDB Agent Lib: Returning result from AI.
83
Simplest P.A.L.: Target script execution completed normally.

PDB session log saved to 'pdb_session.log'.

三度、自動的に c が押されたことになります。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。

著者

JRF ( http://jrf.cocolog-nifty.com/statuses , Twitter (X): @jion_rockford )

このプロジェクトは、大部分が Gemini 2.5 Flash と Pro によって生成されました。

(This document is mainly written in Japanese/UTF8.)

About

The Simplest PDB Automation Layer for AI-Driven Debugging

Topics

python debugger debugging cli automation ai proof-of-concept pdb dev-tools dynamic-execution ai-agent ai-driven-development

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

7 tags

Packages

No packages published

Languages