oagi 0.4.3__tar.gz → 0.5.0__tar.gz

{oagi-0.4.3 → oagi-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oagi
-Version: 0.4.3
+Version: 0.5.0
 Summary: Official API of OpenAGI Foundation
 Project-URL: Homepage, https://github.com/agiopen-org/oagi
 Author-email: OpenAGI Foundation <contact@agiopen.org>

oagi-0.5.0/examples/continued_session.py

@@ -0,0 +1,53 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from oagi import ScreenshotMaker, ShortTask
+
+
+def main():
+    # First session - start a new task
+    print("=== First Session ===")
+    task1 = ShortTask()
+    task1.init_task("Open calculator app")
+
+    image_provider = ScreenshotMaker()
+
+    # Execute a few steps in the first session
+    for i in range(1):
+        image = image_provider()
+        step = task1.step(image)
+        print(f"Session 1, Step {i + 1}: {step.reason}, Actions: {step.actions}")
+
+        if step.stop:
+            break
+
+    # Save the task_id from the first session
+    previous_task_id = task1.task_id
+    print(f"\nFirst session task_id: {previous_task_id}")
+
+    # Second session - continue with context from the first session
+    print("\n=== Second Session (with history) ===")
+    task2 = ShortTask()
+    task2.init_task("Calculate 25 * 4", last_task_id=previous_task_id, history_steps=1)
+
+    # Execute steps with history context
+    for i in range(3):
+        image = image_provider()
+        step = task2.step(image)
+        print(f"Session 2, Step {i + 1}: {step.reason}, Actions: {step.actions}")
+
+        if step.stop:
+            print("✓ Task completed!")
+            break
+
+    print(f"\nSecond session task_id: {task2.task_id}")
+    print(f"Used history from: {task2.last_task_id}")
+
+
+if __name__ == "__main__":
+    main()

{oagi-0.4.3 → oagi-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi"
-version = "0.4.3"
+version = "0.5.0"
 description = "Official API of OpenAGI Foundation"
 readme = "README.md"
 license = { file = "LICENSE" }

{oagi-0.4.3 → oagi-0.5.0}/src/oagi/async_client.py

@@ -91,6 +91,8 @@ class AsyncClient:
         task_id: str | None = None,
         instruction: str | None = None,
         max_actions: int | None = 5,
+        last_task_id: str | None = None,
+        history_steps: int | None = None,
         api_version: str | None = None,
     ) -> LLMResponse:
         """
@@ -103,6 +105,8 @@ class AsyncClient:
             task_id: Task ID for continuing existing task
             instruction: Additional instruction when continuing a session (only works with task_id)
             max_actions: Maximum number of actions to return (1-20)
+            last_task_id: Previous task ID to retrieve history from (only works with task_id)
+            history_steps: Number of historical steps to include from last_task_id (default: 1, max: 10)
             api_version: API version header
 
         Returns:
@@ -127,6 +131,10 @@ class AsyncClient:
             payload["instruction"] = instruction
         if max_actions is not None:
             payload["max_actions"] = max_actions
+        if last_task_id is not None:
+            payload["last_task_id"] = last_task_id
+        if history_steps is not None:
+            payload["history_steps"] = history_steps
 
         logger.info(f"Making async API request to /v1/message with model: {model}")
         logger.debug(

{oagi-0.4.3 → oagi-0.5.0}/src/oagi/async_short_task.py

@@ -30,12 +30,28 @@ class AsyncShortTask(AsyncTask):
         max_steps: int = 5,
         executor: AsyncActionHandler = None,
         image_provider: AsyncImageProvider = None,
+        last_task_id: str | None = None,
+        history_steps: int | None = None,
     ) -> bool:
-        """Run the task in automatic mode with the provided executor and image provider."""
+        """Run the task in automatic mode with the provided executor and image provider.
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps
+            executor: Async handler to execute actions
+            image_provider: Async provider for screenshots
+            last_task_id: Previous task ID to retrieve history from
+            history_steps: Number of historical steps to include
+        """
         logger.info(
             f"Starting async auto mode for task: '{task_desc}' (max_steps: {max_steps})"
         )
-        await self.init_task(task_desc, max_steps=max_steps)
+        await self.init_task(
+            task_desc,
+            max_steps=max_steps,
+            last_task_id=last_task_id,
+            history_steps=history_steps,
+        )
 
         for i in range(max_steps):
             logger.debug(f"Async auto mode step {i + 1}/{max_steps}")

{oagi-0.4.3 → oagi-0.5.0}/src/oagi/async_task.py

@@ -29,10 +29,27 @@ class AsyncTask:
         self.task_id: str | None = None
         self.task_description: str | None = None
         self.model = model
+        self.last_task_id: str | None = None
+        self.history_steps: int | None = None
 
-    async def init_task(self, task_desc: str, max_steps: int = 5):
-        """Initialize a new task with the given description."""
+    async def init_task(
+        self,
+        task_desc: str,
+        max_steps: int = 5,
+        last_task_id: str | None = None,
+        history_steps: int | None = None,
+    ):
+        """Initialize a new task with the given description.
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps (for logging)
+            last_task_id: Previous task ID to retrieve history from
+            history_steps: Number of historical steps to include (default: 1)
+        """
         self.task_description = task_desc
+        self.last_task_id = last_task_id
+        self.history_steps = history_steps
         response = await self.client.create_message(
             model=self.model,
             screenshot="",
@@ -41,6 +58,10 @@ class AsyncTask:
         )
         self.task_id = response.task_id  # Reset task_id for new task
         logger.info(f"Async task initialized: '{task_desc}' (max_steps: {max_steps})")
+        if last_task_id:
+            logger.info(
+                f"Will include {history_steps or 1} steps from previous task: {last_task_id}"
+            )
 
     async def step(
         self, screenshot: Image | bytes, instruction: str | None = None
@@ -74,6 +95,8 @@ class AsyncTask:
                 task_description=self.task_description,
                 task_id=self.task_id,
                 instruction=instruction,
+                last_task_id=self.last_task_id if self.task_id else None,
+                history_steps=self.history_steps if self.task_id else None,
             )
 
             # Update task_id from response

{oagi-0.4.3 → oagi-0.5.0}/src/oagi/short_task.py

@@ -30,12 +30,28 @@ class ShortTask(Task):
         max_steps: int = 5,
         executor: ActionHandler = None,
         image_provider: ImageProvider = None,
+        last_task_id: str | None = None,
+        history_steps: int | None = None,
     ) -> bool:
-        """Run the task in automatic mode with the provided executor and image provider."""
+        """Run the task in automatic mode with the provided executor and image provider.
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps
+            executor: Handler to execute actions
+            image_provider: Provider for screenshots
+            last_task_id: Previous task ID to retrieve history from
+            history_steps: Number of historical steps to include
+        """
         logger.info(
             f"Starting auto mode for task: '{task_desc}' (max_steps: {max_steps})"
         )
-        self.init_task(task_desc, max_steps=max_steps)
+        self.init_task(
+            task_desc,
+            max_steps=max_steps,
+            last_task_id=last_task_id,
+            history_steps=history_steps,
+        )
 
         for i in range(max_steps):
             logger.debug(f"Auto mode step {i + 1}/{max_steps}")

{oagi-0.4.3 → oagi-0.5.0}/src/oagi/sync_client.py

@@ -130,6 +130,8 @@ class SyncClient:
         task_id: str | None = None,
         instruction: str | None = None,
         max_actions: int | None = 5,
+        last_task_id: str | None = None,
+        history_steps: int | None = None,
         api_version: str | None = None,
     ) -> LLMResponse:
         """
@@ -142,6 +144,8 @@ class SyncClient:
             task_id: Task ID for continuing existing task
             instruction: Additional instruction when continuing a session (only works with task_id)
             max_actions: Maximum number of actions to return (1-20)
+            last_task_id: Previous task ID to retrieve history from (only works with task_id)
+            history_steps: Number of historical steps to include from last_task_id (default: 1, max: 10)
             api_version: API version header
 
         Returns:
@@ -166,6 +170,10 @@ class SyncClient:
             payload["instruction"] = instruction
         if max_actions is not None:
             payload["max_actions"] = max_actions
+        if last_task_id is not None:
+            payload["last_task_id"] = last_task_id
+        if history_steps is not None:
+            payload["history_steps"] = history_steps
 
         logger.info(f"Making API request to /v1/message with model: {model}")
         logger.debug(

{oagi-0.4.3 → oagi-0.5.0}/src/oagi/task.py

@@ -28,10 +28,27 @@ class Task:
         self.task_id: str | None = None
         self.task_description: str | None = None
         self.model = model
+        self.last_task_id: str | None = None
+        self.history_steps: int | None = None
 
-    def init_task(self, task_desc: str, max_steps: int = 5):
-        """Initialize a new task with the given description."""
+    def init_task(
+        self,
+        task_desc: str,
+        max_steps: int = 5,
+        last_task_id: str | None = None,
+        history_steps: int | None = None,
+    ):
+        """Initialize a new task with the given description.
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps (for logging)
+            last_task_id: Previous task ID to retrieve history from
+            history_steps: Number of historical steps to include (default: 1)
+        """
         self.task_description = task_desc
+        self.last_task_id = last_task_id
+        self.history_steps = history_steps
         response = self.client.create_message(
             model=self.model,
             screenshot="",
@@ -40,6 +57,10 @@ class Task:
         )
         self.task_id = response.task_id  # Reset task_id for new task
         logger.info(f"Task initialized: '{task_desc}' (max_steps: {max_steps})")
+        if last_task_id:
+            logger.info(
+                f"Will include {history_steps or 1} steps from previous task: {last_task_id}"
+            )
 
     def step(self, screenshot: Image | bytes, instruction: str | None = None) -> Step:
         """Send screenshot to the server and get the next actions.
@@ -71,6 +92,8 @@ class Task:
                 task_description=self.task_description,
                 task_id=self.task_id,
                 instruction=instruction,
+                last_task_id=self.last_task_id if self.task_id else None,
+                history_steps=self.history_steps if self.task_id else None,
             )
 
             # Update task_id from response

{oagi-0.4.3 → oagi-0.5.0}/tests/test_sync_client.py

@@ -19,6 +19,7 @@ from oagi.exceptions import (
     AuthenticationError,
     ConfigurationError,
     RequestTimeoutError,
+    ValidationError,
 )
 from oagi.sync_client import (
     ErrorDetail,
@@ -300,6 +301,143 @@ class TestHelperFunctions:
         mock_open.assert_called_once_with("/path/to/image.png", "rb")
 
 
+class TestSyncClientHistory:
+    """Test the history functionality of SyncClient."""
+
+    @pytest.fixture
+    def base_client_setup(self):
+        """Set up base client with successful response."""
+        client = SyncClient(base_url="http://test.com", api_key="test-key")
+        with patch.object(client.client, "post") as mock_post:
+            mock_response = Mock()
+            mock_response.status_code = 200
+            mock_response.json.return_value = {
+                "id": "resp-123",
+                "task_id": "task-456",
+                "object": "task.completion",
+                "created": 1677652288,
+                "model": "vision-model-v1",
+                "task_description": "Test task",
+                "current_step": 1,
+                "is_complete": False,
+                "actions": [],
+                "usage": {
+                    "prompt_tokens": 100,
+                    "completion_tokens": 50,
+                    "total_tokens": 150,
+                },
+            }
+            mock_post.return_value = mock_response
+            yield client, mock_post
+
+    def test_create_message_with_history(self, base_client_setup):
+        """Test create_message with history parameters."""
+        client, mock_post = base_client_setup
+
+        # Call with history parameters
+        client.create_message(
+            model="vision-model-v1",
+            screenshot="base64_image",
+            task_id="task-456",
+            last_task_id="previous-task",
+            history_steps=2,
+        )
+
+        # Verify request payload includes history params
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        payload = call_args[1]["json"]
+        assert payload["last_task_id"] == "previous-task"
+        assert payload["history_steps"] == 2
+
+    def test_create_message_without_history(self, base_client_setup):
+        """Test create_message without history parameters."""
+        client, mock_post = base_client_setup
+
+        # Call without history parameters
+        client.create_message(
+            model="vision-model-v1",
+            screenshot="base64_image",
+            task_id="task-456",
+        )
+
+        # Verify request payload doesn't include history params
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        payload = call_args[1]["json"]
+        assert "last_task_id" not in payload
+        assert "history_steps" not in payload
+
+    def test_history_validation_error(self):
+        """Test that server validation errors are handled properly."""
+        client = SyncClient(base_url="http://test.com", api_key="test-key")
+
+        with patch.object(client.client, "post") as mock_post:
+            # Mock validation error response
+            mock_response = Mock()
+            mock_response.status_code = 422
+            mock_response.json.return_value = {
+                "error": {
+                    "code": "validation_error",
+                    "message": "last_task_id can only be used when continuing a session with task_id",
+                }
+            }
+            mock_post.return_value = mock_response
+
+            # Try to use last_task_id without task_id
+            with pytest.raises(ValidationError) as exc_info:
+                client.create_message(
+                    model="vision-model-v1",
+                    screenshot="base64_image",
+                    task_description="New task",
+                    last_task_id="previous-task",
+                    history_steps=1,
+                )
+
+            assert "last_task_id can only be used" in str(exc_info.value)
+
+    def test_history_with_instruction(self, base_client_setup):
+        """Test combining history with instruction."""
+        client, mock_post = base_client_setup
+
+        # Call with both history and instruction
+        client.create_message(
+            model="vision-model-v1",
+            screenshot="base64_image",
+            task_id="task-456",
+            instruction="Click submit",
+            last_task_id="previous-task",
+            history_steps=1,
+        )
+
+        # Verify all parameters are included
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        payload = call_args[1]["json"]
+        assert payload["instruction"] == "Click submit"
+        assert payload["last_task_id"] == "previous-task"
+        assert payload["history_steps"] == 1
+
+    def test_history_default_steps(self, base_client_setup):
+        """Test that omitting history_steps works."""
+        client, mock_post = base_client_setup
+
+        # Call with only last_task_id
+        client.create_message(
+            model="vision-model-v1",
+            screenshot="base64_image",
+            task_id="task-456",
+            last_task_id="previous-task",
+        )
+
+        # Verify request
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        payload = call_args[1]["json"]
+        assert payload["last_task_id"] == "previous-task"
+        assert "history_steps" not in payload  # None values aren't sent
+
+
 class TestTraceLogging:
     @pytest.mark.parametrize(
         "trace_headers,expected_logs",

{oagi-0.4.3 → oagi-0.5.0}/tests/test_task.py

@@ -108,6 +108,8 @@ class TestStep:
                 task_description="Test task",
                 task_id="existing-task",
                 instruction=None,
+                last_task_id=None,
+                history_steps=None,
             )
 
             # Verify returned Step
@@ -140,6 +142,8 @@ class TestStep:
                 task_description="Test task",
                 task_id=None,
                 instruction=None,
+                last_task_id=None,
+                history_steps=None,
             )
 
             # Verify task_id was updated
@@ -209,6 +213,8 @@ class TestStep:
                 task_description="Test task",
                 task_id="existing-task",
                 instruction="Click the submit button",
+                last_task_id=None,
+                history_steps=None,
             )
 
             assert isinstance(result, Step)
@@ -281,3 +287,147 @@ class TestIntegrationScenarios:
             # Verify second call used the task_id
             calls = task.client.create_message.call_args_list
             assert calls[1][1]["task_id"] == "task-456"
+
+
+class TestTaskHistory:
+    """Test Task class history functionality."""
+
+    def test_init_task_with_history(self, task, sample_llm_response):
+        """Test init_task with history parameters."""
+        task.client.create_message.return_value = sample_llm_response
+
+        # Initialize task with history
+        task.init_task(
+            "Test task",
+            max_steps=5,
+            last_task_id="previous-task",
+            history_steps=2,
+        )
+
+        # Verify task attributes
+        assert task.task_description == "Test task"
+        assert task.task_id == "task-456"
+        assert task.last_task_id == "previous-task"
+        assert task.history_steps == 2
+
+        # History is not sent during init, only stored
+        task.client.create_message.assert_called_once_with(
+            model="vision-model-v1",
+            screenshot="",
+            task_description="Test task",
+            task_id=None,
+        )
+
+    def test_init_task_without_history(self, task, sample_llm_response):
+        """Test init_task without history parameters."""
+        task.client.create_message.return_value = sample_llm_response
+
+        # Initialize task without history
+        task.init_task("Test task", max_steps=5)
+
+        # Verify task attributes
+        assert task.task_description == "Test task"
+        assert task.task_id == "task-456"
+        assert task.last_task_id is None
+        assert task.history_steps is None
+
+    def test_step_with_history(self, task, sample_llm_response):
+        """Test step method with history (continuing session)."""
+        task.task_description = "Test task"
+        task.task_id = "task-456"  # Already have task_id
+        task.last_task_id = "previous-task"
+        task.history_steps = 2
+        task.client.create_message.return_value = sample_llm_response
+
+        with patch("oagi.task.encode_screenshot_from_bytes") as mock_encode:
+            mock_encode.return_value = "base64_encoded"
+
+            # Call step
+            task.step(b"screenshot_data", instruction="Click submit")
+
+            # Verify API call includes history params
+            task.client.create_message.assert_called_once_with(
+                model="vision-model-v1",
+                screenshot="base64_encoded",
+                task_description="Test task",
+                task_id="task-456",
+                instruction="Click submit",
+                last_task_id="previous-task",
+                history_steps=2,
+            )
+
+    def test_step_history_only_when_continuing(self, task, sample_llm_response):
+        """Test that history is only sent when continuing (task_id exists)."""
+        task.task_description = "Test task"
+        task.last_task_id = "previous-task"
+        task.history_steps = 1
+        task.client.create_message.return_value = sample_llm_response
+
+        with patch("oagi.task.encode_screenshot_from_bytes") as mock_encode:
+            mock_encode.return_value = "base64_encoded"
+
+            # First step - no task_id yet
+            task.task_id = None
+            task.step(b"screenshot1")
+
+            # Verify first call - no history
+            first_call = task.client.create_message.call_args_list[0][1]
+            assert first_call["task_id"] is None
+            assert first_call["last_task_id"] is None
+            assert first_call["history_steps"] is None
+
+            # Task ID should be updated
+            assert task.task_id == "task-456"
+
+            # Second step - now have task_id
+            task.step(b"screenshot2")
+
+            # Verify second call - includes history
+            second_call = task.client.create_message.call_args_list[1][1]
+            assert second_call["task_id"] == "task-456"
+            assert second_call["last_task_id"] == "previous-task"
+            assert second_call["history_steps"] == 1
+
+    def test_init_task_with_default_history_steps(self, task, sample_llm_response):
+        """Test that history_steps can be omitted."""
+        task.client.create_message.return_value = sample_llm_response
+
+        # Initialize task with last_task_id but no history_steps
+        task.init_task(
+            "Test task",
+            max_steps=5,
+            last_task_id="previous-task",
+            # history_steps not specified
+        )
+
+        # Verify task attributes
+        assert task.last_task_id == "previous-task"
+        assert task.history_steps is None  # Not specified
+
+    def test_step_without_history(self, task, sample_llm_response):
+        """Test step method without history (first step)."""
+        task.task_description = "Test task"
+        task.task_id = None  # First step
+        task.client.create_message.return_value = sample_llm_response
+
+        with patch("oagi.task.encode_screenshot_from_bytes") as mock_encode:
+            mock_encode.return_value = "base64_encoded"
+
+            # Call step
+            result = task.step(b"screenshot_data")
+
+            # Verify API call - no history params on first step
+            task.client.create_message.assert_called_once_with(
+                model="vision-model-v1",
+                screenshot="base64_encoded",
+                task_description="Test task",
+                task_id=None,
+                instruction=None,
+                last_task_id=None,
+                history_steps=None,
+            )
+
+            # Verify result
+            assert isinstance(result, Step)
+            assert not result.stop
+            assert len(result.actions) == 2

{oagi-0.4.3 → oagi-0.5.0}/uv.lock

@@ -138,7 +138,7 @@ sdist = { url = "https://files.pythonhosted.org/packages/28/fa/b2ba8229b9381e8f6
 
 [[package]]
 name = "oagi"
-version = "0.4.3"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },