runtess 0.1rc1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of runtess might be problematic. Click here for more details.

runtess-0.1rc1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 mtious
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,253 @@
1
+ Metadata-Version: 2.5
2
+ Name: runtess
3
+ Version: 0.1rc1
4
+ Summary: A Python runtime that enables LLMs to continuously observe, reason, execute, and interact with the outside world.
5
+ Keywords: llm,agent,runtime,python,code-execution,context-management
6
+ Author-email: mtious <mtious@outlook.com>
7
+ Requires-Python: >=3.10
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Project-URL: Repository, https://github.com/mtious/runtess
11
+ Import-Name: runtess
12
+
13
+ # Runtess
14
+
15
+ **A Python runtime that enables LLMs to continuously observe, reason, execute, and interact with the outside world.**
16
+
17
+ Runtess provides a persistent Python execution environment controlled by an LLM.
18
+
19
+ Unlike traditional LLM integrations that treat each model response as an isolated result, Runtess allows an LLM to continuously interact with a shared Python runtime through generated code.
20
+
21
+ The LLM can inspect data, manipulate objects, execute code, modify project files, and use previous execution results to guide subsequent decisions.
22
+
23
+ Rather than being restricted to predefined tools and function calls, the LLM can leverage Python's native capabilities to accomplish complex, multi-step tasks.
24
+
25
+ ## Installation
26
+
27
+ ```bash
28
+ pip install runtess
29
+ ```
30
+
31
+ ## Key Features
32
+
33
+ - **Direct Python Execution** — Allow LLMs to interact with a real Python runtime through generated code.
34
+ - **Persistent Runtime State** — Maintain variables, objects, and execution state across multiple interactions.
35
+ - **Interactive Control** — Allow users to send new instructions or request interruption of ongoing tasks.
36
+ - **Context Recovery** — Automatically handle context window overflow through conversation summarization and recovery.
37
+ - **Execution Feedback** — Return execution results and exceptions to the LLM for iterative problem-solving.
38
+ - **Project Awareness** — Provide the LLM with project source code and file structure as context.
39
+ - **Extensible Integration** — Integrate with different LLM services by implementing a small number of asynchronous methods.
40
+
41
+ ## How It Works
42
+
43
+ Runtess connects an LLM to a persistent Python execution environment through an iterative execution loop.
44
+
45
+ ```text
46
+ User
47
+ |
48
+ v
49
+ LLMRuntime
50
+ |
51
+ v
52
+ LLM API
53
+ |
54
+ v
55
+ Generated Python Code
56
+ |
57
+ v
58
+ Python Runtime
59
+ |
60
+ +--------+--------+
61
+ | |
62
+ v v
63
+ Execution Results Runtime State
64
+ | |
65
+ +--------+--------+
66
+ |
67
+ v
68
+ Next LLM Turn
69
+ ```
70
+
71
+ The LLM generates Python code, which is executed in the runtime environment. Execution results and exceptions are returned to the LLM, allowing it to observe the outcome and decide what to do next.
72
+
73
+ The runtime maintains execution state across multiple interactions, enabling the LLM to build upon previous operations instead of starting from scratch.
74
+
75
+ Users can also intervene in the execution process by sending new instructions or requesting interruption.
76
+
77
+ ## Core Concepts
78
+
79
+ ### 1. Execution Instructions
80
+
81
+ Runtess defines several instruction types to distinguish different operations.
82
+
83
+ | Instruction | Purpose |
84
+ |---|---|
85
+ | `# exec` | Execute Python code to create or modify runtime state. |
86
+ | `# fetch_full` | Evaluate an expression and retrieve its complete result. |
87
+ | `# fetch_abstract` | Evaluate an expression and retrieve a summary of its result. |
88
+ | `# summarize_the_context` | Summarize conversation history to recover from context window overflow. |
89
+ | `# update_prepared_tell_user_content` | Deliver a message to the user. |
90
+
91
+ Each instruction is processed by the runtime, and its execution outcome is fed back into the conversation.
92
+
93
+ ### 2. Persistent Runtime State
94
+
95
+ Runtess maintains a shared Python namespace across executions.
96
+
97
+ The LLM can create variables, define functions, import modules, and reuse previously created objects.
98
+
99
+ This makes it possible to perform multi-step tasks without repeatedly reconstructing the execution environment.
100
+
101
+ ### 3. Interactive Control
102
+
103
+ Runtess supports two-way communication between the user and the LLM.
104
+
105
+ - `tell_assistant()` — Submit new user instructions to the runtime.
106
+ - `interrupt()` — Request interruption of the current task.
107
+ - `tell_user()` — Deliver messages from the runtime to the user.
108
+
109
+ Users can participate in ongoing execution rather than interacting only through isolated request-response cycles.
110
+
111
+ ### 4. Context Recovery
112
+
113
+ When the LLM's context window is exceeded, Runtess attempts to recover the conversation by:
114
+
115
+ 1. Identifying completed execution boundaries.
116
+ 2. Selecting an appropriate historical segment.
117
+ 3. Asking the LLM to summarize the completed history.
118
+ 4. Preserving the remaining conversation.
119
+ 5. Reconstructing the context and continuing execution.
120
+
121
+ This provides a mechanism for maintaining long-running interactive tasks despite context window limitations.
122
+
123
+ ## Demo
124
+
125
+ ### Demo 1: Autonomous Python Bug Fixing
126
+
127
+ This demo demonstrates how an LLM can inspect a Python project, identify a coding error, modify the source code, and save the corrected version.
128
+
129
+ > User: There is a bug in the fletapp.py file in the project. Please fix it and save the corrected version as fletapp_fixed.py.
130
+ >
131
+ > AI: I have fixed the bug in fletapp.py (corrected `page.a_d_d` to `page.add`) and saved it as fletapp_fixed.py.
132
+
133
+ **Task:** Fix a bug in `fletapp.py`.
134
+
135
+ The original code contains an incorrect method call:
136
+
137
+ ```python
138
+ page.a_d_d
139
+ ```
140
+
141
+ The LLM identifies the problem and corrects it to:
142
+
143
+ ```python
144
+ page.add
145
+ ```
146
+
147
+ It then saves the corrected source code as `fletapp_fixed.py`.
148
+
149
+ **Result:** The bug was successfully fixed, and the corrected file was generated.
150
+
151
+ ![Runtess Demo 1](demos/bug_fix/img1.png)
152
+
153
+ #### Run the Demo
154
+
155
+ Install the required packages:
156
+
157
+ ```bash
158
+ pip install runtess lmstudiox flet
159
+
160
+ # Run from the project root directory
161
+ python -m demos.bug_fix.run_demo
162
+ ```
163
+
164
+ Once started, open the following address in your browser:
165
+
166
+ [http://127.0.0.1:8888](http://127.0.0.1:8888)
167
+
168
+ You can interact with the LLM through the web interface.
169
+
170
+ ## Getting Started
171
+
172
+ The main entry point is `LLMRuntime`.
173
+
174
+ To integrate Runtess with an LLM service, subclass `LLMRuntime` and implement two asynchronous methods:
175
+
176
+ - `request_ai(history)` — Send conversation history to an LLM and return its generated Python code.
177
+ - `tell_user(content)` — Deliver messages from the runtime to the user.
178
+
179
+ The following example demonstrates a minimal command-line application using Runtess and LM Studio.
180
+
181
+ ### Example: Interactive Command-Line Runtime
182
+
183
+ Install the dependencies:
184
+
185
+ ```bash
186
+ pip install runtess lmstudiox
187
+ ```
188
+
189
+ Make sure LM Studio is running and the model `qwen3.5-9b` is available through its local API server at `localhost:1234`.
190
+
191
+ ```python
192
+ import asyncio
193
+ from pathlib import Path
194
+
195
+ import lmstudiox
196
+ from runtess import LLMRuntime, ContextWindowExceededError
197
+
198
+
199
+ class MyRuntime(LLMRuntime):
200
+ async def request_ai(self, history):
201
+ async with lmstudiox.AsyncClient("localhost:1234") as client:
202
+ model = await client.llm.model("qwen3.5-9b")
203
+ stream = await model.respond_stream(
204
+ {"messages": history},
205
+ config=lmstudiox.LlmPredictionConfig(enable_thinking=False)
206
+ )
207
+ return ''.join([x.content async for x in stream if x.content])
208
+
209
+ async def tell_user(self, content):
210
+ print(f"\nAI: {content}")
211
+
212
+
213
+ async def main():
214
+ this_dir = Path(__file__).parent
215
+ runtime = MyRuntime(project_dir=this_dir, debug=False)
216
+ runtime_task = asyncio.create_task(runtime.run())
217
+
218
+ print("Runtess is running.")
219
+ print("Enter a message to interact with the AI.")
220
+ print("Press Enter on an empty line to request interruption.")
221
+ print("Press Ctrl+C to exit.\n")
222
+
223
+ try:
224
+ while True:
225
+ message = await asyncio.to_thread(input, "You: ")
226
+ if message.strip():
227
+ await runtime.tell_assistant(message)
228
+ else:
229
+ await runtime.interrupt()
230
+ finally:
231
+ runtime_task.cancel()
232
+ await asyncio.gather(runtime_task, return_exceptions=True)
233
+
234
+ asyncio.run(main())
235
+ ```
236
+
237
+ **Interaction:**
238
+
239
+ - Enter a non-empty message to send it to the AI.
240
+ - Press Enter on an empty line to request interruption of the current task.
241
+ - Press `Ctrl+C` to exit the application.
242
+
243
+ The example demonstrates the basic integration pattern. You can replace `request_ai()` with your preferred LLM service while keeping the same runtime interface.
244
+
245
+ ## Project
246
+
247
+ GitHub Repository:
248
+
249
+ https://github.com/mtious/runtess
250
+
251
+ ## License
252
+
253
+ Runtess is distributed under the license specified in the [LICENSE](LICENSE) file.
@@ -0,0 +1,241 @@
1
+ # Runtess
2
+
3
+ **A Python runtime that enables LLMs to continuously observe, reason, execute, and interact with the outside world.**
4
+
5
+ Runtess provides a persistent Python execution environment controlled by an LLM.
6
+
7
+ Unlike traditional LLM integrations that treat each model response as an isolated result, Runtess allows an LLM to continuously interact with a shared Python runtime through generated code.
8
+
9
+ The LLM can inspect data, manipulate objects, execute code, modify project files, and use previous execution results to guide subsequent decisions.
10
+
11
+ Rather than being restricted to predefined tools and function calls, the LLM can leverage Python's native capabilities to accomplish complex, multi-step tasks.
12
+
13
+ ## Installation
14
+
15
+ ```bash
16
+ pip install runtess
17
+ ```
18
+
19
+ ## Key Features
20
+
21
+ - **Direct Python Execution** — Allow LLMs to interact with a real Python runtime through generated code.
22
+ - **Persistent Runtime State** — Maintain variables, objects, and execution state across multiple interactions.
23
+ - **Interactive Control** — Allow users to send new instructions or request interruption of ongoing tasks.
24
+ - **Context Recovery** — Automatically handle context window overflow through conversation summarization and recovery.
25
+ - **Execution Feedback** — Return execution results and exceptions to the LLM for iterative problem-solving.
26
+ - **Project Awareness** — Provide the LLM with project source code and file structure as context.
27
+ - **Extensible Integration** — Integrate with different LLM services by implementing a small number of asynchronous methods.
28
+
29
+ ## How It Works
30
+
31
+ Runtess connects an LLM to a persistent Python execution environment through an iterative execution loop.
32
+
33
+ ```text
34
+ User
35
+ |
36
+ v
37
+ LLMRuntime
38
+ |
39
+ v
40
+ LLM API
41
+ |
42
+ v
43
+ Generated Python Code
44
+ |
45
+ v
46
+ Python Runtime
47
+ |
48
+ +--------+--------+
49
+ | |
50
+ v v
51
+ Execution Results Runtime State
52
+ | |
53
+ +--------+--------+
54
+ |
55
+ v
56
+ Next LLM Turn
57
+ ```
58
+
59
+ The LLM generates Python code, which is executed in the runtime environment. Execution results and exceptions are returned to the LLM, allowing it to observe the outcome and decide what to do next.
60
+
61
+ The runtime maintains execution state across multiple interactions, enabling the LLM to build upon previous operations instead of starting from scratch.
62
+
63
+ Users can also intervene in the execution process by sending new instructions or requesting interruption.
64
+
65
+ ## Core Concepts
66
+
67
+ ### 1. Execution Instructions
68
+
69
+ Runtess defines several instruction types to distinguish different operations.
70
+
71
+ | Instruction | Purpose |
72
+ |---|---|
73
+ | `# exec` | Execute Python code to create or modify runtime state. |
74
+ | `# fetch_full` | Evaluate an expression and retrieve its complete result. |
75
+ | `# fetch_abstract` | Evaluate an expression and retrieve a summary of its result. |
76
+ | `# summarize_the_context` | Summarize conversation history to recover from context window overflow. |
77
+ | `# update_prepared_tell_user_content` | Deliver a message to the user. |
78
+
79
+ Each instruction is processed by the runtime, and its execution outcome is fed back into the conversation.
80
+
81
+ ### 2. Persistent Runtime State
82
+
83
+ Runtess maintains a shared Python namespace across executions.
84
+
85
+ The LLM can create variables, define functions, import modules, and reuse previously created objects.
86
+
87
+ This makes it possible to perform multi-step tasks without repeatedly reconstructing the execution environment.
88
+
89
+ ### 3. Interactive Control
90
+
91
+ Runtess supports two-way communication between the user and the LLM.
92
+
93
+ - `tell_assistant()` — Submit new user instructions to the runtime.
94
+ - `interrupt()` — Request interruption of the current task.
95
+ - `tell_user()` — Deliver messages from the runtime to the user.
96
+
97
+ Users can participate in ongoing execution rather than interacting only through isolated request-response cycles.
98
+
99
+ ### 4. Context Recovery
100
+
101
+ When the LLM's context window is exceeded, Runtess attempts to recover the conversation by:
102
+
103
+ 1. Identifying completed execution boundaries.
104
+ 2. Selecting an appropriate historical segment.
105
+ 3. Asking the LLM to summarize the completed history.
106
+ 4. Preserving the remaining conversation.
107
+ 5. Reconstructing the context and continuing execution.
108
+
109
+ This provides a mechanism for maintaining long-running interactive tasks despite context window limitations.
110
+
111
+ ## Demo
112
+
113
+ ### Demo 1: Autonomous Python Bug Fixing
114
+
115
+ This demo demonstrates how an LLM can inspect a Python project, identify a coding error, modify the source code, and save the corrected version.
116
+
117
+ > User: There is a bug in the fletapp.py file in the project. Please fix it and save the corrected version as fletapp_fixed.py.
118
+ >
119
+ > AI: I have fixed the bug in fletapp.py (corrected `page.a_d_d` to `page.add`) and saved it as fletapp_fixed.py.
120
+
121
+ **Task:** Fix a bug in `fletapp.py`.
122
+
123
+ The original code contains an incorrect method call:
124
+
125
+ ```python
126
+ page.a_d_d
127
+ ```
128
+
129
+ The LLM identifies the problem and corrects it to:
130
+
131
+ ```python
132
+ page.add
133
+ ```
134
+
135
+ It then saves the corrected source code as `fletapp_fixed.py`.
136
+
137
+ **Result:** The bug was successfully fixed, and the corrected file was generated.
138
+
139
+ ![Runtess Demo 1](demos/bug_fix/img1.png)
140
+
141
+ #### Run the Demo
142
+
143
+ Install the required packages:
144
+
145
+ ```bash
146
+ pip install runtess lmstudiox flet
147
+
148
+ # Run from the project root directory
149
+ python -m demos.bug_fix.run_demo
150
+ ```
151
+
152
+ Once started, open the following address in your browser:
153
+
154
+ [http://127.0.0.1:8888](http://127.0.0.1:8888)
155
+
156
+ You can interact with the LLM through the web interface.
157
+
158
+ ## Getting Started
159
+
160
+ The main entry point is `LLMRuntime`.
161
+
162
+ To integrate Runtess with an LLM service, subclass `LLMRuntime` and implement two asynchronous methods:
163
+
164
+ - `request_ai(history)` — Send conversation history to an LLM and return its generated Python code.
165
+ - `tell_user(content)` — Deliver messages from the runtime to the user.
166
+
167
+ The following example demonstrates a minimal command-line application using Runtess and LM Studio.
168
+
169
+ ### Example: Interactive Command-Line Runtime
170
+
171
+ Install the dependencies:
172
+
173
+ ```bash
174
+ pip install runtess lmstudiox
175
+ ```
176
+
177
+ Make sure LM Studio is running and the model `qwen3.5-9b` is available through its local API server at `localhost:1234`.
178
+
179
+ ```python
180
+ import asyncio
181
+ from pathlib import Path
182
+
183
+ import lmstudiox
184
+ from runtess import LLMRuntime, ContextWindowExceededError
185
+
186
+
187
+ class MyRuntime(LLMRuntime):
188
+ async def request_ai(self, history):
189
+ async with lmstudiox.AsyncClient("localhost:1234") as client:
190
+ model = await client.llm.model("qwen3.5-9b")
191
+ stream = await model.respond_stream(
192
+ {"messages": history},
193
+ config=lmstudiox.LlmPredictionConfig(enable_thinking=False)
194
+ )
195
+ return ''.join([x.content async for x in stream if x.content])
196
+
197
+ async def tell_user(self, content):
198
+ print(f"\nAI: {content}")
199
+
200
+
201
+ async def main():
202
+ this_dir = Path(__file__).parent
203
+ runtime = MyRuntime(project_dir=this_dir, debug=False)
204
+ runtime_task = asyncio.create_task(runtime.run())
205
+
206
+ print("Runtess is running.")
207
+ print("Enter a message to interact with the AI.")
208
+ print("Press Enter on an empty line to request interruption.")
209
+ print("Press Ctrl+C to exit.\n")
210
+
211
+ try:
212
+ while True:
213
+ message = await asyncio.to_thread(input, "You: ")
214
+ if message.strip():
215
+ await runtime.tell_assistant(message)
216
+ else:
217
+ await runtime.interrupt()
218
+ finally:
219
+ runtime_task.cancel()
220
+ await asyncio.gather(runtime_task, return_exceptions=True)
221
+
222
+ asyncio.run(main())
223
+ ```
224
+
225
+ **Interaction:**
226
+
227
+ - Enter a non-empty message to send it to the AI.
228
+ - Press Enter on an empty line to request interruption of the current task.
229
+ - Press `Ctrl+C` to exit the application.
230
+
231
+ The example demonstrates the basic integration pattern. You can replace `request_ai()` with your preferred LLM service while keeping the same runtime interface.
232
+
233
+ ## Project
234
+
235
+ GitHub Repository:
236
+
237
+ https://github.com/mtious/runtess
238
+
239
+ ## License
240
+
241
+ Runtess is distributed under the license specified in the [LICENSE](LICENSE) file.
@@ -0,0 +1,24 @@
1
+ [build-system]
2
+ requires = ["flit_core >=3.11,<5"]
3
+ build-backend = "flit_core.buildapi"
4
+
5
+ [project]
6
+ name = "runtess"
7
+ version = "0.1rc1"
8
+ description = "A Python runtime that enables LLMs to continuously observe, reason, execute, and interact with the outside world."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = {file = "LICENSE"}
12
+ authors = [{name = "mtious", email = "mtious@outlook.com"}]
13
+ keywords = [
14
+ "llm",
15
+ "agent",
16
+ "runtime",
17
+ "python",
18
+ "code-execution",
19
+ "context-management",
20
+ ]
21
+ dependencies = []
22
+
23
+ [project.urls]
24
+ Repository = "https://github.com/mtious/runtess"
@@ -0,0 +1,416 @@
1
+ import sys, re, traceback, ast, inspect, json, platform, os, asyncio
2
+ from os.path import abspath
3
+ from copy import deepcopy
4
+ from typing import Literal, Any
5
+ from pathlib import Path
6
+
7
+ this_dir = Path(__file__).parent
8
+
9
+ def get_environment_info():
10
+ s = {
11
+ 'os_platform': platform.platform(),
12
+ 'python_version': sys.version,
13
+ 'python_implementation': platform.python_implementation(),
14
+ 'python_executable': sys.executable,
15
+ 'process_entry_file': getattr(sys.modules['__main__'], '__file__', None),
16
+ 'process_pid': os.getpid(),
17
+ }
18
+ s = '\n'.join(f"- {k}: {json.dumps(v, ensure_ascii=False)}" for k, v in s.items())
19
+ return s
20
+
21
+ system_env_history = []
22
+
23
+ c = f'''
24
+ Conflicts between instructions given earlier and the instructions in this message must be resolved in favor of this message.
25
+
26
+ You are the controller of the current Python runtime. You must complete the tasks assigned to you by the user.
27
+
28
+ I will provide you with the relevant source code so that you can understand the architecture of the entire project, how you came into existence, and where you are situated within it.
29
+
30
+ Whenever you respond, output Python code directly that can be executed by `exec` or `eval`, and the code must begin with one of the following identifiers:
31
+ | Identifier | Description |
32
+ | ------------------------------------ | ---------------------------------------------------------- |
33
+ | `# exec` | Execute code with `exec` to create or modify Runtime state, such as creating variables, importing modules, defining functions, and modifying objects |
34
+ | `# fetch_full` | Evaluate an expression with `eval` and retrieve the complete result |
35
+ | `# fetch_abstract` | Evaluate an expression with `eval` and retrieve a summary of the result |
36
+ | `# summarize_the_context` | Evaluate an expression with `eval` to summarize the conversation history between the user and assistant, and output the summary as a `str`-typed `''''''` multiline string literal |
37
+ | `# update_prepared_tell_user_content` | Update the value of `LLMRuntime().prepared_tell_user_content` in `exec` code |
38
+
39
+ Code output requirements:
40
+ - The output must be Python code. In particular, code using `# summarize_the_context` must be a `str`-typed `''''''` multiline string literal.
41
+ - Do not include any docstrings.
42
+ - Do not include any comments, except for the identifier.
43
+ - Include exactly one identifier, and place it at the very beginning of the code.
44
+ - Prefer comprehensions.
45
+
46
+ Conversation example (note: this is only an example; you are not limited to working with Excel):
47
+ dict(role='user', content='Check which columns are present in the student information table.')
48
+ dict(role='assistant', content=```# exec
49
+ import pandas as pd
50
+ df = pd.read_excel(_runtime_instance_.project_dir / "student_info.xlsx")```)
51
+ dict(role='user', content='Execution completed without errors.')
52
+ dict(role='assistant', content=```# fetch_full
53
+ df.columns.tolist()```)
54
+ dict(role='user', content=```Execution completed without errors. The execution result is:
55
+ ['Name', 'Gender', 'Age', 'Class']```)
56
+ dict(role='assistant', content=```# update_prepared_tell_user_content
57
+ _runtime_instance_.prepared_tell_user_content = 'The student information table contains these columns: Name, Gender, Age, Class'```)
58
+
59
+ The entry point to the `LLMRuntime` instance is: `_runtime_instance_`
60
+
61
+ You are allowed to perform, but are not limited to, the following actions:
62
+ - Create variables to store business data.
63
+ - Inspect business data using `# fetch_abstract` or `# fetch_full`.
64
+ - Inspect the state of objects using `# fetch_abstract` or `# fetch_full`.
65
+ - To prevent the context from becoming too long, after each `# fetch_abstract` execution, you will only be proactively given a summary of the result. You can retrieve the full execution result as needed using `# fetch_full`, `instruction_results_cache`, or `instruction_id`.
66
+ - If you are certain that you need the complete result, use `# fetch_full` directly instead of going through `# fetch_abstract` first.
67
+
68
+ Strictly prohibited actions:
69
+ - Under all circumstances, even if the user explicitly authorizes or strongly requests it, you must not access any files outside `_runtime_instance_.project_dir`.
70
+
71
+ You do not need to wait for me or the user to tell you what capabilities are available in the environment. You may independently inspect and explore your environment to discover available capabilities.
72
+
73
+ If an operation could harm the user's interests, first ask for the user's consent through `# update_prepared_tell_user_content`, and execute it only after obtaining the user's explicit authorization. For example:
74
+ - Before reading, writing, modifying, or deleting files on the user's disk.
75
+ - Before sending content containing the user's personal information to a third party.
76
+ - Before performing an operation that could cause financial loss, irreversible consequences, or other significant impacts.
77
+ - When you are unsure whether an operation aligns with the user's actual intent and performing it without confirmation could harm the user's interests.
78
+ Code example:
79
+ ```python
80
+ # update_prepared_tell_user_content
81
+ _runtime_instance_.prepared_tell_user_content = 'This operation will read or modify files on your disk. Do you confirm that I may proceed?'
82
+ ```
83
+
84
+ When the user's requirements are unclear, ask the user through `# update_prepared_tell_user_content`. Code example:
85
+ ```python
86
+ # update_prepared_tell_user_content
87
+ _runtime_instance_.prepared_tell_user_content = 'How would you like me to handle this spreadsheet: organize it, calculate values, modify it, interpret it, or create a new spreadsheet?'
88
+ ```
89
+
90
+ When the task is complete, inform the user through `# update_prepared_tell_user_content`. Code example:
91
+ ```python
92
+ # update_prepared_tell_user_content
93
+ _runtime_instance_.prepared_tell_user_content = 'I have removed the duplicate rows from this spreadsheet. A total of 12 duplicate records were removed.'
94
+ ```
95
+
96
+ When the user chats with you, respond through `# update_prepared_tell_user_content`. Code example:
97
+ ```python
98
+ # update_prepared_tell_user_content
99
+ _runtime_instance_.prepared_tell_user_content = 'Haha, it looks like you had a lot of fun today!'
100
+ ```
101
+
102
+ Choose the level of inspection independently based on the information needs of the current task:
103
+ - For large objects and complex containers, prefer `# fetch_abstract` to obtain a summary.
104
+ - For results that may contain large amounts of data, prefer `# fetch_abstract`.
105
+ - For operations where you know that the complete data is required, use `# fetch_full` directly.
106
+ - Do not traverse the entire Runtime without a specific purpose.
107
+
108
+ When using `# summarize_the_context` to summarize the context, note the following:
109
+ - The output code must be a `str`-typed `''''''` multiline string literal, and the resulting multiline string must be parseable by `eval`.
110
+ - The summary does not need to include system messages; summarize only the conversation between the user and assistant.
111
+ When using `# summarize_the_context` to summarize the context, the summary must include:
112
+ - Tasks that have been completed and their results.
113
+ - Important variable names and object names, along with their purposes.
114
+ - Side effects that have occurred.
115
+ - Current task progress.
116
+ - Goals that have not yet been completed.
117
+ - Key facts on which subsequent operations depend.
118
+
119
+ You need to understand the user's mental model. For example, when the user asks, "What is the total sales amount?",
120
+ the user may want you to inspect sales-total data in a descendant file under `_runtime_instance_.project_dir`,
121
+ or they may want you to inspect the value of a variable named `sales_total` in the current namespace.
122
+ If you are unsure, you can ask, for example: 'Do you want me to find or calculate the total sales amount in a file under the project directory?'
123
+
124
+ Current runtime environment:
125
+ {get_environment_info()}
126
+ '''
127
+
128
+ system_env_history.append({'role': 'system', 'content': c.strip()})
129
+
130
+ for file in this_dir.rglob('*.py'):
131
+ path = file.as_posix()
132
+ text = file.read_text().strip()
133
+ system_env_history.append({'role': 'system', 'content': f"# Module {path}:\n\n{text}"})
134
+
135
+ def merge_adjacent_roles(history: list[dict[Literal['role', 'content'], str]], sep: str = '\n--------\n') -> list[dict[Literal['role', 'content'], str]]:
136
+ result = []
137
+ for x in history:
138
+ if x is HistoryBoundary:
139
+ continue
140
+ if result and result[-1]['role'] == x['role']:
141
+ result[-1]['content'] += sep + x['content']
142
+ else:
143
+ result.append(dict(role=x['role'], content=x['content']))
144
+ return result
145
+
146
+ class InstructionResult:
147
+ value: dict[Literal['result', 'result_type', 'result_repr', 'result_repr_length', 'result_repr_prefix'], Any]
148
+ def __init__(self, value):
149
+ self.value = value
150
+
151
+ class ContextWindowExceededError(Exception): ... # The model context window has been exceeded
152
+ class Interrupt: ...
153
+ class HistoryBoundary: ...
154
+
155
+ class LLMRuntime:
156
+ '''
157
+ # Import
158
+ from runtess import LLMRuntime, ContextWindowExceededError
159
+
160
+ # Notes
161
+ - Subclass `LLMRuntime` and override the `request_ai` and `tell_user` methods.
162
+ '''
163
+
164
+ project_dir: Path # Project directory. The assistant may access only paths within this directory, not files outside it.
165
+ instruction_results_cache: dict[int: InstructionResult]
166
+ instruction_id: int # ID of the Python code output by the assistant
167
+ discussion: dict[Literal['history'], list[dict[Literal['role', 'content'], str]]]
168
+
169
+ def __init__(self, project_dir: Path, *, project_scripts: list[Path]|None=None, debug=True):
170
+ assistant_namespace = sys.modules['__main__'].__dict__
171
+ if '_runtime_instance_' in assistant_namespace:
172
+ raise RuntimeError('_runtime_instance_ is a reserved framework attribute.')
173
+ self.instruction_results_cache = {}
174
+ self.project_dir = Path(abspath(project_dir))
175
+ self.env_history = deepcopy(system_env_history)
176
+ self.env_history.append({'role': 'system', 'content': f"_runtime_instance_.project_dir: {self.project_dir.as_posix()}"})
177
+ scripts = {}
178
+ if project_scripts is None:
179
+ project_scripts = list(self.project_dir.rglob('*.py'))
180
+ for file in project_scripts:
181
+ file = Path(abspath(file))
182
+ if not file.is_relative_to(self.project_dir):
183
+ raise ValueError(f"File {file} is not inside the project directory.")
184
+ scripts[file.as_posix()] = file.read_text().strip()
185
+ for path, text in scripts.items():
186
+ self.env_history.append({'role': 'system', 'content': f"# Module {path}:\n\n{text}"})
187
+ self.discussion = {
188
+ 'history': [],
189
+ }
190
+ self.instruction_id = 0
191
+ self.control_queue: asyncio.Queue[tuple[dict[Literal['type', 'data'], str], asyncio.Queue]] = asyncio.Queue(maxsize=1)
192
+ self.prepared_tell_user_content = ''
193
+ self.debug = debug
194
+ assistant_namespace['_runtime_instance_'] = self
195
+
196
+ @property
197
+ def project_files_history(self):
198
+ project_files = '\n'.join(x.as_posix() for x in self.project_dir.rglob('*') if x.is_file())
199
+ return [{'role': 'system', 'content': f"# project_files:\n\n{project_files}"}]
200
+
201
+ async def request_ai(self, history: list[dict[Literal['role', 'content'], str]]) -> str:
202
+ ''' Send the conversation history to the AI model and retrieve the Python code output by the assistant. This method is called internally by `LLMRuntime()._call_ai`. '''
203
+ raise RuntimeError('Subclasses must override request_ai() to connect an AI service.')
204
+
205
+ async def tell_user(self, content: str, /):
206
+ ''' Present a message to the user. '''
207
+ raise RuntimeError('Subclasses must override tell_user() to implement user-facing message delivery.')
208
+
209
+ async def interrupt(self):
210
+ d = dict(type='interrupt', data=None)
211
+ try:
212
+ self.control_queue.put_nowait((d, receipt := asyncio.Queue()))
213
+ if not await receipt.get():
214
+ raise asyncio.QueueFull
215
+ return True
216
+ except asyncio.QueueFull:
217
+ return False
218
+
219
+ async def tell_assistant(self, content: str, /):
220
+ try:
221
+ d = dict(type='user_message', data=content)
222
+ self.control_queue.put_nowait((d, receipt := asyncio.Queue()))
223
+ if not await receipt.get():
224
+ raise asyncio.QueueFull
225
+ return True
226
+ except asyncio.QueueFull:
227
+ return False
228
+
229
+ async def run(self):
230
+ while True:
231
+ info, receipt = await self.control_queue.get()
232
+ receipt.put_nowait(True)
233
+ if info.get('type') != 'user_message':
234
+ continue
235
+ self.discussion['history'] += [dict(role='user', content=info['data']), HistoryBoundary]
236
+ unknown_count = 0
237
+ try:
238
+ while True:
239
+ if not self.control_queue.empty():
240
+ info, receipt = self.control_queue.get_nowait()
241
+ match info['type']:
242
+ case 'interrupt':
243
+ receipt.put_nowait(True)
244
+ break
245
+ case 'user_message':
246
+ self.control_queue.put_nowait((info, receipt))
247
+ break
248
+ r = await self._call_ai()
249
+ instruction, instruction_type = r[:2]
250
+ if instruction_type == 'unknown':
251
+ unknown_count += 1
252
+ if unknown_count < 4:
253
+ if unknown_count == 2: # Append a corrective prompt after two consecutive errors
254
+ self.discussion['history'] += [
255
+ dict(role='assistant', content=instruction),
256
+ dict(role='user', content="Your previous output did not comply with the required format and was ignored. For every response, output Python code directly, beginning with one of these identifiers: [`# exec`, `# fetch_abstract`, `# fetch_full`, `# summarize_the_context`, `# update_prepared_tell_user_content`]."),
257
+ ]
258
+ continue
259
+ raise RuntimeError('The maximum number of consecutive assistant output errors has been reached (4).') # Raise an exception after four consecutive errors
260
+ unknown_count = 0
261
+ self.instruction_id += 1
262
+ instruction_message = dict(role='assistant', content=instruction)
263
+ user_content_prefix = json.dumps(dict(instruction_id=self.instruction_id, instruction_type=instruction_type), ensure_ascii=False)
264
+
265
+ if not r[2]:
266
+ if self.debug:
267
+ print(r[3])
268
+ self.discussion['history'] += [instruction_message, {'role': 'user', 'content': f'{user_content_prefix} Execution completed with the following exception:\n\n{r[3]}'}]
269
+ continue
270
+
271
+ if instruction_type == 'update_prepared_tell_user_content':
272
+ if not self.control_queue.empty():
273
+ info, receipt = self.control_queue.get_nowait()
274
+ receipt.put_nowait(False)
275
+ self.discussion['history'].append(instruction_message)
276
+ await self.tell_user(self.prepared_tell_user_content)
277
+ break
278
+
279
+ match instruction_type:
280
+ case 'exec':
281
+ self.discussion['history'] += [instruction_message, {'role': 'user', 'content': f'{user_content_prefix} Execution completed without errors.'}, HistoryBoundary]
282
+ case 'fetch_abstract'|'fetch_full':
283
+ item = {}
284
+ item['result'] = result = r[3]
285
+ item['result_type'] = result_type = type(result).__qualname__
286
+ item['result_repr'] = result_repr = repr(result)
287
+ item['result_repr_length'] = result_repr_length = len(result_repr)
288
+ item['result_repr_prefix'] = result_repr_prefix = result_repr[:100]
289
+ item = InstructionResult(item)
290
+ self.instruction_results_cache[self.instruction_id] = item
291
+ if instruction_type == 'fetch_abstract':
292
+ abstract = ['# result_type:', result_type, '# result_repr_length:', str(result_repr_length), '# result_repr_prefix:', result_repr_prefix]
293
+ abstract = '\n\n'.join(abstract)
294
+ self.discussion['history'] += [instruction_message,
295
+ {'role': 'user', 'content': f'{user_content_prefix} Execution completed without errors. The execution result summary is:\n\n{abstract}'},
296
+ HistoryBoundary]
297
+ else:
298
+ self.discussion['history'] += [instruction_message,
299
+ {'role': 'user', 'content': f'{user_content_prefix} Execution completed without errors. The execution result is:\n\n# result_repr:\n\n{result_repr}'},
300
+ HistoryBoundary]
301
+ case 'summarize_the_context':
302
+ self.discussion['history'] = [dict(role='assistant', content=r[3])]
303
+ except Exception as e:
304
+ if not self.control_queue.empty():
305
+ info, receipt = self.control_queue.get_nowait()
306
+ receipt.put_nowait(False)
307
+ error = traceback.format_exc()
308
+ self.discussion['history'].append({'role': 'user', 'content': f'The following exception occurred during task execution:\n\n{error}'})
309
+ await self.tell_user(f"Task error: {e}")
310
+
311
+ async def _call_ai(self):
312
+ assistant_namespace = sys.modules['__main__'].__dict__
313
+
314
+ async def run_exec(instruction: str):
315
+ code = compile(instruction, 'assistant.py', 'exec', flags=ast.PyCF_ALLOW_TOP_LEVEL_AWAIT, dont_inherit=True)
316
+ result = eval(code, assistant_namespace, assistant_namespace)
317
+ if inspect.isawaitable(result):
318
+ await result
319
+
320
+ async def run_eval(instruction: str):
321
+ code = compile(instruction, 'assistant.py', 'eval', flags=ast.PyCF_ALLOW_TOP_LEVEL_AWAIT, dont_inherit=True)
322
+ result = eval(code, assistant_namespace, assistant_namespace)
323
+ if inspect.isawaitable(result):
324
+ result = await result
325
+ return result
326
+
327
+ history = merge_adjacent_roles(self.env_history + self.project_files_history + self.discussion['history'])
328
+ try:
329
+ instruction = await self.request_ai(history)
330
+ except ContextWindowExceededError:
331
+ d_history = self.discussion['history']
332
+ if not d_history:
333
+ raise RuntimeError(f"Too much base context information!")
334
+ indices = [i for i, x in enumerate(d_history) if x is HistoryBoundary]
335
+ tip = "The current context is too long. Please execute `# summarize_the_context` to produce a summary. The output code must meet these requirements: it must begin with `# summarize_the_context`; it must be a `str`-typed `''''''` multiline string literal, and the resulting multiline string must be parseable by `eval`; the summary does not need to include system messages and should summarize only the conversation between the user and assistant."
336
+ tip = dict(role='user', content=tip)
337
+ if indices and d_history[indices[-1]] is HistoryBoundary:
338
+ indices.pop()
339
+ for index in reversed(indices):
340
+ try:
341
+ left = d_history[:index]
342
+ right = d_history[index + 1:]
343
+ history = merge_adjacent_roles(self.env_history + self.project_files_history + left + tip)
344
+ summary = await self.request_ai(history)
345
+ if not re.match(r'^\s*#\s*summarize_the_context\s', summary):
346
+ raise ContextWindowExceededError
347
+ try:
348
+ summary = await run_eval(summary)
349
+ except Exception:
350
+ raise ContextWindowExceededError
351
+ if type(summary) is not str:
352
+ raise ContextWindowExceededError
353
+ except ContextWindowExceededError:
354
+ pass
355
+ else:
356
+ summary = dict(role='assistant', content=summary)
357
+ history = merge_adjacent_roles(self.env_history + self.project_files_history + [summary] + right)
358
+ instruction = await self.request_ai(history)
359
+ self.discussion['history'] = [summary] + right
360
+ break
361
+ else:
362
+ raise
363
+ if self.debug:
364
+ print('-' * 30)
365
+ print(instruction)
366
+ instruction = instruction.lstrip()
367
+
368
+ for s in ('```python', '```py'):
369
+ if instruction.startswith(s):
370
+ instruction = instruction.rstrip()
371
+ if instruction.endswith(e := '```'):
372
+ instruction = instruction.removeprefix(s).removesuffix(e)
373
+ break
374
+
375
+ try:
376
+ ast.parse(instruction)
377
+ except:
378
+ return instruction, 'unknown'
379
+
380
+ if re.match(r'^\s*#\s*exec\s', instruction):
381
+ try:
382
+ await run_exec(instruction)
383
+ return instruction, 'exec', True
384
+ except Exception:
385
+ return instruction, 'exec', False, traceback.format_exc()
386
+ elif re.match(r'^\s*#\s*fetch_abstract\s', instruction):
387
+ try:
388
+ return instruction, 'fetch_abstract', True, await run_eval(instruction)
389
+ except Exception:
390
+ return instruction, 'fetch_abstract', False, traceback.format_exc()
391
+ elif re.match(r'^\s*#\s*fetch_full\s', instruction):
392
+ try:
393
+ return instruction, 'fetch_full', True, await run_eval(instruction)
394
+ except Exception:
395
+ return instruction, 'fetch_full', False, traceback.format_exc()
396
+ elif re.match(r'^\s*#\s*update_prepared_tell_user_content\s', instruction):
397
+ try:
398
+ await run_exec(instruction)
399
+ return instruction, 'update_prepared_tell_user_content', True
400
+ except Exception:
401
+ return instruction, 'update_prepared_tell_user_content', False, traceback.format_exc()
402
+ elif re.match(r'^\s*#\s*summarize_the_context\s', instruction):
403
+ try:
404
+ summary = await run_eval(instruction)
405
+ if type(summary) is not str:
406
+ raise TypeError("The code output for `# summarize_the_context` must be a multiline string literal.")
407
+ return instruction, 'summarize_the_context', True, summary
408
+ except Exception:
409
+ return instruction, 'summarize_the_context', False, traceback.format_exc()
410
+ else:
411
+ return instruction, 'unknown'
412
+
413
+ __all__ = [
414
+ 'LLMRuntime',
415
+ 'ContextWindowExceededError',
416
+ ]