Merge pull request #236 from askui/chore/act_conversation_with_caching

Migrate act() to conversation-based architecture with Speaker pattern and add caching v2 features.

Author: philipph-askui

.gitignore

@@ -169,5 +169,6 @@ reports/
 /askui_chat.db-shm
 /askui_chat.db-wal
 .cache/
+.askui_cache/*
 
 bom.json

README.md

@@ -112,17 +112,18 @@ with ComputerAgent() as agent:
 
 Ready to build your first agent? Check out our documentation:
 
-1. **[Start Here](docs/00_overview.md)** - Overview and core concepts
-2. **[Setup](docs/01_setup.md)** - Installation and configuration
-3. **[Using Agents](docs/02_using_agents.md)** - Using the AskUI ComputerAgent and AndroidAgent
-4. **[System Prompts](docs/03_prompting.md)** - How to write effective instructions
-5. **[Using Models](docs/04_using_models.md)** - Using different models as backbone for act, get, and locate
-6. **[BYOM](docs/05_bring_your_own_model_provider.md)** - use your own model cloud by plugging in your own model provider
-7. **[Caching](docs/06_caching.md)** - Optimize performance and costs
-8. **[Tools](docs/07_tools.md)** - Extend agent capabilities
-9. **[Reporting](docs/08_reporting.md)** - Obtain agent logs as execution reports and summaries as test reports
-10. **[Observability](docs/09_observability_telemetry_tracing.md)** - Monitor and debug agents
-11. **[Extracting Data](docs/10_extracting_data.md)** - Extracting structured data from screenshots and files
+0. **[Start Here](docs/00_overview.md)** - Overview and core concepts
+1. **[Setup](docs/01_setup.md)** - Installation and configuration
+2. **[Using Agents](docs/02_using_agents.md)** - Using the AskUI ComputerAgent and AndroidAgent
+3. **[System Prompts](docs/03_prompting.md)** - How to write effective instructions
+4. **[Using Models](docs/04_using_models.md)** - Using different models as backbone for act, get, and locate
+5. **[BYOM](docs/05_bring_your_own_model_provider.md)** - use your own model cloud by plugging in your own model provider
+6. **[Caching](docs/06_caching.md)** - Optimize performance and costs
+7. **[Tools](docs/07_tools.md)** - Extend agent capabilities
+8. **[Reporting](docs/08_reporting.md)** - Obtain agent logs as execution reports and summaries as test reports
+9. **[Observability](docs/09_observability_telemetry_tracing.md)** - Monitor and debug agents
+10. **[Extracting Data](docs/10_extracting_data.md)** - Extracting structured data from screenshots and files
+11. **[Callbacks](docs/11_callbacks.md)** - Inject custom logic into the control loop
 
 **Official documentation:** [docs.askui.com](https://docs.askui.com)
 

SIMPLIFICATION_CONCEPT.md

@@ -90,6 +90,9 @@ Understand what data is collected and how to opt out.
 ### 10 - Extracting Data
 **Topics**: Using `get()`, file support (PDF. Excel, Word, CSV), structured data extraction, response schemas
 
+### 11 - Callbacks
+**Topics**: Inject custom logic at different positions of the control loop through callbacks
+
 Extract information from screens and files using the `get()` method with Pydantic models.
 
 ## Additional Resources

docs/00_overview.md

@@ -118,7 +118,7 @@ with WebVisionAgent() as agent:
         "Log in with username 'testuser' and password 'testpass123'",
         # CAUTION: this will also override all other MessageSettings
         # eventually provided earlier!
-        settings=ActSettings(messages=MessageSettings(system=prompt))
+        act_settings=ActSettings(messages=MessageSettings(system=prompt))
     )
 ```
 
@@ -170,7 +170,7 @@ prompt = ActSystemPrompt(
 with WebVisionAgent() as agent:
     agent.act(
         "Your task",
-        settings=ActSettings(messages=MessageSettings(system=prompt))
+        act_settings=ActSettings(messages=MessageSettings(system=prompt))
     )
 ```
 
@@ -329,6 +329,6 @@ with WebVisionAgent() as agent:
         "Find a laptop under $1000 and add it to cart",
         # CAUTION: this will also override all other MessageSettings
         # eventually provided earlier!
-        settings=ActSettings(messages=MessageSettings(system=prompt))
+        act_settings=ActSettings(messages=MessageSettings(system=prompt))
     )
 ```

docs/03_prompting.md

@@ -49,7 +49,7 @@ Environment variables:
 
 If you want to use Anthropic models directly from the Anthropic API with your Anthropic API key, you can use:
 - `AnthropicVlmProvider` for `act()`
-- `AntrhopicImageQAProvider` for `get()`
+- `AnthropicImageQAProvider` for `get()`
 
 ```python
 import os
@@ -78,12 +78,11 @@ If you want to use Google models directly from the Google API with your Google A
 - `GoogleImageQAProvider` for `get()`
 
 ```python
-import os
 from askui import AgentSettings, ComputerAgent
-from askui.model_providers import AnthropicVlmProvider
+from askui.model_providers import GoogleImageQAProvider
 
 with ComputerAgent(settings=AgentSettings(
-    vlm_provider=GoogleImageQAProvider(
+    image_qa_provider=GoogleImageQAProvider(
         model_id="gemini-2.5-pro",
     ),
 )) as agent: