feat: Add Context management system with data persistence

- Add Context, ContextManager, and ContextSync modules
- Implement 15+ new API models for context operations
- Add comprehensive documentation and examples
- Include extensive test coverage
- Update core AGB client with context integration

This major update enables persistent data storage and
file synchronization across AGB sessions.

Author: AgbAccount

.gitignore

@@ -130,6 +130,7 @@ dmypy.json
 .vscode/
 .idea/
 .cursor/
+.cursorrules
 CLAUDE.md
 .DS_Store
 

CHANGES.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.3.0] - 2025-10-15
+
+### New Features
+- **Context Management System**: Complete context management with persistent data storage, file operations, and synchronization
+- **Enhanced Logging**: Integrated Loguru for better log formatting and structured logging across all modules
+
+### API Enhancements
+- **Context API**: New context endpoints for CRUD operations, file management, and synchronization with region support
+- **Session Integration**: Enhanced session management with context synchronization during lifecycle
+
+### Documentation & Testing
+- **Context Documentation**: Comprehensive usage guides, API reference, and response type documentation
+- **Testing**: Complete test coverage for context operations, file management, and synchronization features
+
+### Bug Fixes
+- **API & HTTP**: Fixed parameter validation, async request issues, and data serialization problems
+- **Infrastructure**: Updated dependencies, improved CI/CD, and resolved type checking issues
+
 ## [0.2.2] - 2025-09-23
 ### Bug Fixes
 - remove oss related code and docs

README.md

@@ -88,7 +88,7 @@ For comprehensive documentation, guides, and examples, visit:
 
 3. Install dependencies:
    ```bash
-   pip install -e .[dev,test]
+   pip install -e ."[dev,test]"
    ```
 
 ## License

agb/__init__.py

@@ -3,5 +3,15 @@
 from .api.http_client import HTTPClient
 from .session import Session
 from .session_params import CreateSessionParams
+from .context import Context, ContextService, ContextResult, ContextListResult
+from .context_manager import ContextManager, ContextStatusData, ContextInfoResult, ContextSyncResult
+from .context_sync import ContextSync, SyncPolicy, UploadPolicy, DownloadPolicy, DeletePolicy, ExtractPolicy, UploadStrategy, DownloadStrategy
 
-__all__ = ["AGB", "Session", "CreateSessionParams", "HTTPClient", "Client"]
+__all__ = [
+    "AGB", "Session", "CreateSessionParams", "HTTPClient", "Client",
+    # Context related exports
+    "Context", "ContextService", "ContextResult", "ContextListResult",
+    "ContextManager", "ContextStatusData", "ContextInfoResult", "ContextSyncResult",
+    "ContextSync", "SyncPolicy", "UploadPolicy", "DownloadPolicy", "DeletePolicy", "ExtractPolicy",
+    "UploadStrategy", "DownloadStrategy",
+]

agb/agb.py

@@ -13,12 +13,16 @@
 from agb.api.models import (
     CreateSessionRequest,
     CreateSessionResponse,
-    ReleaseSessionRequest,
+    CreateMcpSessionRequestPersistenceDataList,
 )
 from agb.config import Config, load_config
 from agb.model.response import DeleteResult, SessionResult
 from agb.session import BaseSession, Session
 from agb.session_params import CreateSessionParams
+from agb.context import ContextService
+from agb.logger import get_logger, log_operation_start, log_operation_success, log_warning
+
+logger = get_logger(__name__)
 
 
 class AGB:
@@ -58,6 +62,9 @@ def __init__(self, api_key: str = "", cfg: Optional[Config] = None):
         self._sessions: Dict[str, Session] = {}
         self._lock = Lock()
 
+        # Initialize context service
+        self.context = ContextService(self)
+
     def create(self, params: Optional[CreateSessionParams] = None) -> SessionResult:
         """
         Create a new session in the AGB cloud environment.
@@ -78,21 +85,30 @@ def create(self, params: Optional[CreateSessionParams] = None) -> SessionResult:
             if params.image_id:
                 request.image_id = params.image_id
 
-            response: CreateSessionResponse = self.client.create_mcp_session(request)
+            # Flag to indicate if we need to wait for context synchronization
+            needs_context_sync = False
 
-            # Check if response is empty
-            if response is None:
-                return SessionResult(
-                    request_id="",
-                    success=False,
-                    error_message="OpenAPI client returned None response",
-                )
+            if params.context_syncs:
+                persistence_data_list = []
+                for context_sync in params.context_syncs:
+                    if context_sync.policy:
+                        policy_json = json.dumps(context_sync.policy.to_dict(), ensure_ascii=False)
+                        persistence_data_list.append(CreateMcpSessionRequestPersistenceDataList(
+                            context_id=context_sync.context_id,
+                            path=context_sync.path,
+                            policy=policy_json,
+                        ))
+
+                request.persistence_data_list = persistence_data_list
+                needs_context_sync = len(persistence_data_list) > 0
+
+            response: CreateSessionResponse = self.client.create_mcp_session(request)
 
             try:
-                print("Response body:")
-                print(response.to_dict())
+                logger.debug("Response body:")
+                logger.debug(response.to_dict())
             except Exception:
-                print(f"Response: {response}")
+                logger.debug(f"Response: {response}")
 
             # Extract request ID
             request_id_attr = getattr(response, "request_id", "")
@@ -120,8 +136,8 @@ def create(self, params: Optional[CreateSessionParams] = None) -> SessionResult:
             # ResourceUrl is optional in CreateMcpSession response
             resource_url = response.get_resource_url()
 
-            print("session_id =", session_id)
-            print("resource_url =", resource_url)
+            logger.info(f"session_id = {session_id}")
+            logger.info(f"resource_url = {resource_url}")
 
             # Create Session object
             session = Session(self, session_id)
@@ -134,11 +150,49 @@ def create(self, params: Optional[CreateSessionParams] = None) -> SessionResult:
             with self._lock:
                 self._sessions[session_id] = session
 
+            # If we have persistence data, wait for context synchronization
+            if needs_context_sync:
+                log_operation_start("Context synchronization", "Waiting for completion")
+
+                # Wait for context synchronization to complete
+                max_retries = 150  # Maximum number of retries
+                retry_interval = 2  # Seconds to wait between retries
+
+                import time
+                for retry in range(max_retries):
+                    # Get context status data
+                    info_result = session.context.info()
+
+                    # Check if all context items have status "Success" or "Failed"
+                    all_completed = True
+                    has_failure = False
+
+                    for item in info_result.context_status_data:
+                        logger.info(f"📁 Context {item.context_id} status: {item.status}, path: {item.path}")
+
+                        if item.status != "Success" and item.status != "Failed":
+                            all_completed = False
+                            break
+
+                        if item.status == "Failed":
+                            has_failure = True
+                            logger.error(f"❌ Context synchronization failed for {item.context_id}: {item.error_message}")
+
+                    if all_completed or not info_result.context_status_data:
+                        if has_failure:
+                            log_warning("Context synchronization completed with failures")
+                        else:
+                            log_operation_success("Context synchronization")
+                        break
+
+                    logger.info(f"⏳ Waiting for context synchronization, attempt {retry+1}/{max_retries}")
+                    time.sleep(retry_interval)
+
             # Return SessionResult with request ID
             return SessionResult(request_id=request_id, success=True, session=session)
 
         except Exception as e:
-            print("Error calling create_mcp_session:", e)
+            logger.error(f"Error calling create_mcp_session: {e}")
             return SessionResult(
                 request_id="",
                 success=False,
@@ -155,66 +209,30 @@ def list(self) -> List[BaseSession]:
         with self._lock:
             return list(self._sessions.values())
 
-    def delete(self, session: Session) -> DeleteResult:
+    def delete(self, session: BaseSession, sync_context: bool = False) -> DeleteResult:
         """
         Delete a session by session object.
 
         Args:
-            session (Session): The session to delete.
+            session (BaseSession): The session to delete.
+            sync_context (bool, optional): Whether to sync context before deletion. Defaults to False.
 
         Returns:
             DeleteResult: Result indicating success or failure and request ID.
         """
         try:
-            # Create request to release the session
-            request = ReleaseSessionRequest(
-                authorization=f"Bearer {self.api_key}",
-                session_id=session.session_id,
-            )
-
-            # Make the API call
-            response = self.client.release_mcp_session(request)
+            # Delete the session and get the result
+            delete_result = session.delete(sync_context=sync_context)
 
-            # Check if response is empty
-            if response is None:
-                return DeleteResult(
-                    request_id="",
-                    success=False,
-                    error_message="OpenAPI client returned None response",
-                )
+            with self._lock:
+                self._sessions.pop(session.session_id, None)
 
-            # Check response type, if it's ReleaseSessionResponse, use new parsing method
-            if hasattr(response, "is_successful"):
-                # This is a ReleaseSessionResponse object
-                if response.is_successful():
-                    # Remove from local cache
-                    with self._lock:
-                        self._sessions.pop(session.session_id, None)
-
-                    request_id_attr = getattr(response, "request_id", "")
-                    return DeleteResult(request_id=request_id_attr or "", success=True)
-                else:
-                    error_msg = (
-                        response.get_error_message() or "Failed to delete session"
-                    )
-                    request_id_attr = getattr(response, "request_id", "")
-                    return DeleteResult(
-                        request_id=request_id_attr or "",
-                        success=False,
-                        error_message=error_msg,
-                    )
-            else:
-                request_id_attr = getattr(response, "request_id", "")
-                return DeleteResult(
-                    request_id=request_id_attr or "",
-                    success=False,
-                    error_message="Failed to delete session",
-                )
+            return delete_result
 
         except Exception as e:
-            print("Error calling release_mcp_session:", e)
-            # In case of error, return failure result with error message
+            logger.error(f"Error calling delete_mcp_session: {e}")
             return DeleteResult(
+                request_id="",
                 success=False,
-                error_message=f"Failed to delete session {session.session_id}: {e}",
+                error_message=f"Failed to delete session: {e}",
             )

agb/api/base_service.py

@@ -9,6 +9,9 @@
 from agb.api.models import CallMcpToolRequest
 from agb.exceptions import AGBError
 from agb.model import OperationResult
+from agb.logger import get_logger
+
+logger = get_logger(__name__)
 
 
 class BaseService:
@@ -85,10 +88,10 @@ def _call_mcp_tool(
             if hasattr(response, "is_tool_successful"):
                 # This is a CallMcpToolResponse object
                 try:
-                    print("Response body:")
-                    print(json.dumps(response.json_data, ensure_ascii=False, indent=2))
+                    logger.debug("Response body:")
+                    logger.debug(json.dumps(response.json_data, ensure_ascii=False, indent=2))
                 except Exception:
-                    print(f"Response: {response}")
+                    logger.debug(f"Response: {response}")
 
                 if response.is_tool_successful():
                     # Tool execution successful