|
1 | 1 | # dialoghelper |
2 | 2 |
|
3 | | -A Python library for programmatic dialog manipulation in [Solveit](https://solve.it.com), fast.ai's Dialog Engineering web application. It provides both user-callable functions and AI-accessible tools for creating, reading, updating, and managing dialog messages. |
4 | 3 |
|
5 | | -## What is Solveit? |
| 4 | +<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! --> |
6 | 5 |
|
7 | | -**Solveit** is a "Dialog Engineering" web application that combines interactive code execution with AI assistance. Unlike ChatGPT (pure chat) or Jupyter (pure code), Solveit merges both paradigms into a single workspace. |
| 6 | +## Usage |
8 | 7 |
|
9 | | -### Core Concepts |
| 8 | +### Installation |
10 | 9 |
|
11 | | -- **Instance**: A persistent Linux container with your files and running kernels. Each user can have multiple instances. |
12 | | -- **Dialog**: An `.ipynb` file containing messages. Like a Jupyter notebook, but with AI integration. Each open dialog runs its own Python kernel. |
13 | | -- **Message**: The fundamental unit—similar to a Jupyter cell, but with three types: |
| 10 | +Install from [pypi](https://pypi.org/project/dialoghelper/) |
14 | 11 |
|
15 | | -| Type | Purpose | Example | |
16 | | -|------|---------|---------| |
17 | | -| `code` | Python execution | `print("hello")` | |
18 | | -| `note` | Markdown documentation | `# My Notes` | |
19 | | -| `prompt` | AI interaction | "Explain this function" | |
20 | | - |
21 | | -### How AI Context Works |
22 | | - |
23 | | -When you send a prompt to the AI: |
24 | | - |
25 | | -1. **All messages above** the current prompt are collected |
26 | | -2. Messages marked as "hidden" (`skipped=True`) are excluded |
27 | | -3. If context exceeds the model limit, oldest non-pinned messages are dropped |
28 | | -4. The AI sees code, outputs, notes, and previous prompts/responses |
29 | | - |
30 | | -Key implications: |
31 | | -- Working at the **bottom** of a dialog = **more context** (all messages above) |
32 | | -- Working **higher up** = less context |
33 | | -- **Pinning** a message (`p` key) keeps it in context even when truncation occurs |
34 | | - |
35 | | -### Tools: AI-Callable Functions |
36 | | - |
37 | | -Solveit lets the AI call Python functions directly. Users declare tools in messages using `&` followed by backticks: |
38 | | - |
39 | | -``` |
40 | | -&`my_function` # Expose single tool |
41 | | -&`[func1, func2, func3]` # Expose multiple tools |
42 | | -``` |
43 | | - |
44 | | -When the AI needs to use a tool, Solveit executes it in the kernel and returns the result. |
45 | | - |
46 | | -## Installation |
47 | | - |
48 | | -The latest version is always pre-installed in Solveit. To manually install (not recommended): |
49 | | - |
50 | | -```bash |
51 | | -pip install dialoghelper |
| 12 | +``` sh |
| 13 | +$ pip install dialoghelper |
52 | 14 | ``` |
53 | 15 |
|
54 | | -## What is dialoghelper? |
55 | | - |
56 | | -dialoghelper is a programmatic interface to Solveit dialogs. It enables: |
57 | | - |
58 | | -- **Dialog manipulation**: Add, update, delete, and search messages |
59 | | -- **AI tool integration**: Expose functions as tools the AI can call |
60 | | -- **Context generation**: Convert folders, repos, and symbols into AI context |
61 | | -- **Screen capture**: Capture browser screenshots for AI analysis |
62 | | -- **Tmux integration**: Read terminal buffers from tmux sessions |
63 | | - |
64 | | -## Modules |
65 | | - |
66 | | -| Module | Source Notebook | Description | |
67 | | -|--------|-----------------|-------------| |
68 | | -| `core` | `nbs/00_core.ipynb` | Core dialog manipulation (add/update/delete messages, search, context helpers) | |
69 | | -| `capture` | `nbs/01_capture.ipynb` | Screen capture functionality for AI vision | |
70 | | -| `inspecttools` | `nbs/02_inspecttools.ipynb` | Symbol inspection (`symsrc`, `getval`, `getdir`, etc.) | |
71 | | -| `tmux` | `nbs/03_tmux.ipynb` | Tmux buffer reading tools | |
72 | | -| `stdtools` | — | Re-exports all tools from dialoghelper + fastcore.tools | |
73 | | - |
74 | | -## Solveit Tools |
75 | | - |
76 | | -**Tools** are functions the AI can call directly during a conversation. A function is usable as a tool if it has: |
77 | | - |
78 | | -1. **Type annotations** for ALL parameters |
79 | | -2. **A docstring** describing what it does |
80 | | - |
81 | | -```python |
82 | | -# Valid tool |
83 | | -def greet(name: str) -> str: |
84 | | - "Greet someone by name" |
85 | | - return f"Hello, {name}!" |
86 | | - |
87 | | -# Not a tool (missing type annotation) |
88 | | -def greet(name): |
89 | | - "Greet someone by name" |
90 | | - return f"Hello, {name}!" |
91 | | - |
92 | | -# Not a tool (missing docstring) |
93 | | -def greet(name: str) -> str: return f"Hello, {name}!" |
94 | | -``` |
95 | | - |
96 | | -### Exposing Tools to the AI |
97 | | - |
98 | | -In a Solveit dialog, reference tools using `&` followed by backticks: |
99 | | - |
100 | | -``` |
101 | | -&`greet` # Single tool |
102 | | -&`[add_msg, update_msg, del_msg]` # Multiple tools |
103 | | -``` |
104 | | - |
105 | | -### Tool Info Functions |
106 | | - |
107 | | -These functions add notes to your dialog listing available tools: |
108 | | - |
109 | | -| Function | Lists tools from | |
110 | | -|----------|------------------| |
111 | | -| `tool_info()` | `dialoghelper.core` | |
112 | | -| `fc_tool_info()` | `fastcore.tools` (rg, sed, view, create, etc.) | |
113 | | -| `inspect_tool_info()` | `dialoghelper.inspecttools` | |
114 | | -| `tmux_tool_info()` | `dialoghelper.tmux` | |
115 | | - |
116 | | -### Tools vs Programmatic Functions |
117 | | - |
118 | | -Some functions are designed for AI tool use; others are meant to be called directly from code: |
119 | | - |
120 | | -| AI Tools | Programmatic Use | |
121 | | -|----------|------------------| |
122 | | -| `add_msg`, `update_msg`, `del_msg` | | |
123 | | -| `find_msgs`, `read_msg`, `view_dlg` | `call_endp` (raw endpoint access) | |
124 | | -| `symsrc`, `getval`, `getdir` | `resolve` (returns actual Python object) | |
125 | | - |
126 | | -## Usage Examples |
127 | | - |
128 | | -```python |
129 | | -from dialoghelper import * |
130 | | - |
131 | | -# Add a note message |
132 | | -add_msg("Hello from code!", msg_type='note') |
133 | | - |
134 | | -# Add a code message |
135 | | -add_msg("print('Hello')", msg_type='code') |
136 | | - |
137 | | -# Search for messages |
138 | | -results = find_msgs("pattern", msg_type='code') |
139 | | - |
140 | | -# View entire dialog structure |
141 | | -print(view_dlg()) |
142 | | - |
143 | | -# Generate context from a folder |
144 | | -ctx_folder('.', types='py', max_total=5000) |
145 | | -``` |
146 | | - |
147 | | -## Development: nbdev Project Structure |
148 | | - |
149 | | -dialoghelper is an [nbdev](https://nbdev.fast.ai) project. **Notebooks are the source of truth**—the `.py` files are auto-generated. |
150 | | - |
151 | | -### Notebook ↔ Python File Mapping |
152 | | - |
153 | | -| Notebook | Generated File | |
154 | | -|----------|----------------| |
155 | | -| `nbs/00_core.ipynb` | `dialoghelper/core.py` | |
156 | | -| `nbs/01_capture.ipynb` | `dialoghelper/capture.py` | |
157 | | -| `nbs/02_inspecttools.ipynb` | `dialoghelper/inspecttools.py` | |
158 | | -| `nbs/03_tmux.ipynb` | `dialoghelper/tmux.py` | |
159 | | - |
160 | | -### Workflow |
161 | | - |
162 | | -1. Edit notebooks in `nbs/` |
163 | | -2. Run `nbdev_export()` to generate `.py` files |
164 | | -3. Never edit `.py` files directly—they'll be overwritten |
165 | | - |
166 | | -## License |
167 | | - |
168 | | -Apache 2.0 |
| 16 | +### Documentation |
169 | 17 |
|
| 18 | +Documentation can be found hosted on this GitHub [repository](https://github.com/AnswerDotAI/dialoghelper)’s [pages](https://AnswerDotAI.github.io/dialoghelper/). |
0 commit comments