thanh-kit 2.5.0 → 2.5.2

package/templates/skills/google-adk-python/references/sessions-state-memory-artifacts.md

@@ -0,0 +1,131 @@
+# Sessions, State, Memory, Artifacts
+
+## ToolContext.state
+
+Ephemeral dict persisting across tool calls within session.
+
+```python
+from google.adk.tools.tool_context import ToolContext
+
+def save_user(user_id: str, name: str, tool_context: ToolContext) -> dict:
+    if "users" not in tool_context.state:
+        tool_context.state["users"] = {}
+    tool_context.state["users"][user_id] = name
+    return {"status": "saved"}
+
+def get_user(user_id: str, tool_context: ToolContext) -> str:
+    return tool_context.state.get("users", {}).get(user_id, "not_found")
+
+def increment(tool_context: ToolContext) -> int:
+    count = tool_context.state.get("counter", 0) + 1
+    tool_context.state["counter"] = count
+    return count
+```
+
+Lifecycle: Created per session, cleared on end, not shared.
+
+## Artifacts
+
+Versioned binary storage.
+
+```python
+from google.genai import types
+from google.adk.tools.tool_context import ToolContext
+
+async def save_text(name: str, content: str, tool_context: ToolContext) -> dict:
+    part = types.Part(inline_data=types.Blob(mime_type="text/plain", data=content.encode()))
+    version = await tool_context.save_artifact(name, part)
+    return {"name": name, "version": version}
+
+async def save_image(name: str, bytes: bytes, tool_context: ToolContext) -> dict:
+    part = types.Part(inline_data=types.Blob(mime_type="image/png", data=bytes))
+    version = await tool_context.save_artifact(name, part)
+    return {"name": name, "version": version}
+
+async def load_text(name: str, tool_context: ToolContext) -> str:
+    artifact = await tool_context.load_artifact(name)
+    return artifact.inline_data.data.decode() if artifact else None
+
+async def load_version(name: str, version: int, tool_context: ToolContext) -> str:
+    artifact = await tool_context.load_artifact(name, version=version)
+    return artifact.inline_data.data.decode() if artifact else None
+```
+
+Versioning: Each save creates new version (1, 2, 3...), load without version returns latest.
+
+## Session Services
+
+```python
+from google.adk.sessions.in_memory_session_service import InMemorySessionService
+from google.adk.sessions.vertex_ai_session_service import VertexAiSessionService
+from google.adk.sessions.spanner_session_service import SpannerSessionService
+from google.adk.runners import Runner
+
+# Dev
+session_service = InMemorySessionService()
+
+# Prod (Vertex)
+session_service = VertexAiSessionService(project_id="my-project", location="us-central1")
+
+# Prod (Spanner)
+session_service = SpannerSessionService(
+    project_id="my-project", instance_id="my-instance", database_id="sessions"
+)
+
+runner = Runner(agent=root_agent, session_service=session_service)
+```
+
+## Memory
+
+Long-term recall across sessions.
+
+```python
+from google.adk.memory import MemoryService
+
+memory_service = MemoryService(project_id="my-project", location="us-central1")
+runner = Runner(agent=root_agent, session_service=session_service, memory_service=memory_service)
+```
+
+**Comparison:** State (ephemeral, dict), Artifacts (versioned binary, session), Memory (long-term, cross-session)
+
+## Runner
+
+```python
+from google.adk.runners import Runner
+
+runner = Runner(agent=root_agent, session_service=session_service)
+
+# Production (streaming)
+async def execute():
+    async for event in runner.run_async("Query", session_id="user-123"):
+        if event.text: print(event.text, end="")
+        if event.tool_call: print(f"\nTool: {event.tool_call.name}")
+
+# Bidi-streaming
+async def live():
+    async for event in runner.run_live(session_id="user-456"):
+        if event.server_content: print(event.server_content)
+        if user_has_input(): await event.send(get_user_input())
+
+# Sync (debug)
+result = runner.run("Query", session_id="debug")
+```
+
+## Invocation Lifecycle
+
+1. Session retrieval 2. Context creation 3. Agent execution 4. Event streaming 5. Compaction
+
+```python
+runner = Runner(agent=root_agent, session_service=session_service, compaction_threshold=20)
+await runner.compact_session("long-session")
+```
+
+## Best Practices
+
+- State: temporary session data
+- Artifacts: binary/large data
+- Memory: long-term knowledge
+- Session service by env (InMemory dev, Vertex/Spanner prod)
+- Enable compaction for long conversations
+- run_async for production, run_live for bidirectional, run for debug
+- Clean old sessions, version artifacts

package/templates/skills/google-adk-python/references/tools-and-mcp-integration.md

@@ -0,0 +1,146 @@
+# Tools and MCP Integration
+
+## Custom Tools
+
+Python functions (sync/async) with optional `ToolContext`.
+
+```python
+def calculator(operation: str, a: float, b: float) -> float:
+    """Perform math operations.
+    Args: operation ('add'|'subtract'|'multiply'|'divide'), a, b
+    Returns: Result
+    """
+    ops = {"add": a + b, "subtract": a - b, "multiply": a * b, "divide": a / b}
+    return ops[operation]
+```
+
+**Async with ToolContext:**
+
+```python
+from google.adk.tools.tool_context import ToolContext
+
+async def fetch(url: str, tool_context: ToolContext) -> dict:
+    cache = tool_context.state.get("cache", {})
+    if url in cache: return cache[url]
+    data = await http_client.get(url)
+    cache[url] = data
+    tool_context.state["cache"] = cache
+    return data
+```
+
+## ToolContext
+
+Props: `state` (dict), `save_artifact()`, `load_artifact()`
+
+```python
+def store(key: str, value: str, tool_context: ToolContext) -> dict:
+    tool_context.state[key] = value
+    return {"status": "saved"}
+
+from google.genai import types
+
+async def save_doc(name: str, content: str, tool_context: ToolContext) -> dict:
+    part = types.Part(inline_data=types.Blob(mime_type="text/plain", data=content.encode()))
+    version = await tool_context.save_artifact(name, part)
+    return {"name": name, "version": version}
+
+async def load_doc(name: str, tool_context: ToolContext) -> str:
+    artifact = await tool_context.load_artifact(name)
+    return artifact.inline_data.data.decode() if artifact else None
+```
+
+## Built-in Tools
+
+```python
+from google.adk.tools import google_search, load_artifacts, BuiltInCodeExecutor
+
+executor = BuiltInCodeExecutor()
+agent = Agent(name="agent", model="gemini-2.5-flash", tools=[google_search, load_artifacts, executor])
+```
+
+## MCP Integration
+
+```python
+from google.adk.tools.mcp_tool import StdioConnectionParams
+from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
+from mcp import StdioServerParameters
+
+filesystem_mcp = MCPToolset(
+    connection_params=StdioConnectionParams(
+        server_params=StdioServerParameters(
+            command='npx',
+            args=['-y', '@modelcontextprotocol/server-filesystem', '/home/user/docs']
+        ),
+        timeout=5
+    ),
+    tool_filter=['read_file', 'list_directory']
+)
+
+agent = Agent(name="agent", model="gemini-2.5-flash", tools=[filesystem_mcp])
+```
+
+**Multiple servers:**
+
+```python
+git_mcp = MCPToolset(
+    connection_params=StdioConnectionParams(
+        server_params=StdioServerParameters(command='npx', args=['-y', '@modelcontextprotocol/server-git']),
+        timeout=10
+    )
+)
+
+postgres_mcp = MCPToolset(
+    connection_params=StdioConnectionParams(
+        server_params=StdioServerParameters(
+            command='npx', args=['-y', '@modelcontextprotocol/server-postgres', 'postgresql://localhost/db']
+        ),
+        timeout=15
+    )
+)
+
+agent = Agent(name="agent", model="gemini-2.5-flash", tools=[filesystem_mcp, git_mcp, postgres_mcp])
+```
+
+## Tool Filtering
+
+```python
+# List
+MCPToolset(connection_params=params, tool_filter=['read_file', 'write_file'])
+
+# Lambda
+MCPToolset(connection_params=params, tool_filter=lambda t: t.name.startswith('read_'))
+```
+
+## LongRunningFunctionTool
+
+```python
+from google.adk.tools.long_running_tool import LongRunningFunctionTool
+
+async def approve(amount: float) -> dict:
+    return {"approved": True}
+
+tool = LongRunningFunctionTool(func=approve)
+agent = Agent(name="agent", model="gemini-2.5-flash", tools=[tool])
+```
+
+## ExampleTool
+
+```python
+from google.adk.tools.example_tool import ExampleTool
+
+examples = ExampleTool(examples=[
+    {"input": "2+2?", "output": "4"},
+    {"input": "Capital of France?", "output": "Paris"}
+])
+
+agent = Agent(name="agent", model="gemini-2.5-flash", tools=[examples])
+```
+
+## Best Practices
+
+- Docstrings with Args/Returns for schema
+- Async for I/O
+- ToolContext.state for session data
+- Artifacts for binary/large data
+- Filter MCP tools to reduce context
+- Validate inputs

package/templates/skills/install.ps1

@@ -12,7 +12,9 @@ param(
     [switch]$Y = $false,           # Skip all prompts and auto-confirm
     [switch]$WithAdmin = $false,   # Use admin-requiring package managers (choco)
     [switch]$Resume = $false,      # Resume from previous interrupted installation
-    [switch]$RetryFailed = $false  # Retry previously failed packages
+    [switch]$RetryFailed = $false, # Retry previously failed packages
+    [ValidateSet("auto", "winget", "scoop", "choco")]
+    [string]$PreferPackageManager = "auto"  # Preferred package manager (soft fallback to auto if unavailable)
 )
 
 # Configuration
@@ -81,6 +83,15 @@ function Track-Skipped {
 function Initialize-State {
     if ($Resume -and (Test-Path $StateFile)) {
         Write-Info "Resuming from previous installation..."
+        # Load state and validate preference consistency
+        $state = Get-Content $StateFile -Raw | ConvertFrom-Json
+        if ($state.PSObject.Properties['prefer_package_manager']) {
+            if ($state.prefer_package_manager -ne $Script:PreferPackageManager) {
+                Write-Warning "Preference changed from '$($state.prefer_package_manager)' to '$($Script:PreferPackageManager)'"
+                Write-Warning "Using original preference: $($state.prefer_package_manager)"
+                $Script:PreferPackageManager = $state.prefer_package_manager
+            }
+        }
         return
     }
 
@@ -89,6 +100,7 @@ function Initialize-State {
         version = 1
         started_at = (Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ")
         last_updated = (Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ")
+        prefer_package_manager = $Script:PreferPackageManager
         phases = @{
             chocolatey = "pending"
             system_deps = "pending"
@@ -173,17 +185,34 @@ function Test-Administrator {
     return $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
 }
 
-# Check if command exists
+# Check if command exists and is functional (not just in PATH)
+# Validates: command exists, is not a broken alias, and responds to --version
 function Test-Command {
     param([string]$Command)
     try {
-        if (Get-Command $Command -ErrorAction SilentlyContinue) {
-            return $true
+        $cmd = Get-Command $Command -ErrorAction SilentlyContinue
+        if (-not $cmd) {
+            return $false
         }
+
+        # Skip aliases that don't resolve to applications
+        if ($cmd.CommandType -eq 'Alias') {
+            $resolved = Get-Command $cmd.Definition -ErrorAction SilentlyContinue
+            if (-not $resolved -or $resolved.CommandType -ne 'Application') {
+                return $false
+            }
+        }
+
+        # For package managers, verify they actually respond
+        if ($Command -in @('winget', 'scoop', 'choco')) {
+            $null = & $Command --version 2>$null
+            return ($LASTEXITCODE -eq 0)
+        }
+
+        return $true
     } catch {
         return $false
     }
-    return $false
 }
 
 # Check if Visual Studio Build Tools are installed (not just in PATH)
@@ -316,8 +345,32 @@ function Find-Python {
     return $null
 }
 
-# Get available package manager (priority: winget > scoop > choco)
+# Get available package manager with preference support (soft fallback to auto-detection)
+# Priority for auto: winget > scoop > choco
 function Get-PackageManager {
+    param([string]$Preference = "auto")
+
+    # If preference specified, try it first
+    if ($Preference -ne "auto") {
+        if (Test-Command $Preference) {
+            return $Preference
+        }
+        # Auto-detect for better warning message
+        $autoDetected = $null
+        if (Test-Command "winget") { $autoDetected = "winget" }
+        elseif (Test-Command "scoop") { $autoDetected = "scoop" }
+        elseif (Test-Command "choco") { $autoDetected = "choco" }
+
+        if ($autoDetected) {
+            Write-Warning "Preferred '$Preference' not found, using auto-detected: $autoDetected"
+            return $autoDetected
+        } else {
+            Write-Warning "Preferred '$Preference' not found, no package manager available"
+            return $null
+        }
+    }
+
+    # Auto-detection (priority: winget > scoop > choco)
     if (Test-Command "winget") { return "winget" }
     if (Test-Command "scoop") { return "scoop" }
     if (Test-Command "choco") { return "choco" }
@@ -337,9 +390,16 @@ function Install-WithPackageManager {
         [string]$Category = "optional"  # "critical" or "optional"
     )
 
-    $pm = Get-PackageManager
+    $pm = Get-PackageManager -Preference $Script:PreferPackageManager
 
     switch ($pm) {
+        $null {
+            # No package manager available - provide manual install guidance
+            Write-Warning "$DisplayName not installed. No package manager available."
+            Write-Info "Install manually from: $ManualUrl"
+            Track-Failure -Category $Category -Name $DisplayName -Reason "no package manager"
+            return $false
+        }
         "winget" {
             Write-Info "Installing $DisplayName via winget..."
             # Try user scope first, fallback to machine scope
@@ -442,7 +502,7 @@ function Install-Chocolatey {
 
     # Check if we have winget/scoop - no need for choco then
     if ((Test-Command "winget") -or (Test-Command "scoop")) {
-        $pm = Get-PackageManager
+        $pm = Get-PackageManager -Preference $Script:PreferPackageManager
         Write-Info "Using $pm as package manager (Chocolatey not needed)"
         return $false
     }
@@ -481,7 +541,7 @@ function Install-Chocolatey {
 function Install-SystemDeps {
     Write-Header "Installing System Dependencies"
 
-    $pm = Get-PackageManager
+    $pm = Get-PackageManager -Preference $Script:PreferPackageManager
     if ($pm) {
         Write-Info "Using package manager: $pm"
     } else {
@@ -696,6 +756,10 @@ function Try-PipInstall {
 function Setup-PythonEnv {
     Write-Header "Setting Up Python Environment"
 
+    # Suppress pip version check notices that trigger PowerShell NativeCommandError
+    # Set early to affect all pip operations in this function
+    $env:PIP_DISABLE_PIP_VERSION_CHECK = "1"
+
     # Track successful and failed installations
     $successfulSkills = [System.Collections.ArrayList]::new()
     $failedSkills = [System.Collections.ArrayList]::new()
@@ -714,7 +778,32 @@ function Setup-PythonEnv {
         return  # Don't exit, return and let final report show
     }
 
-    # Create virtual environment
+    # Create virtual environment with uv fallback
+    function New-Venv {
+        param([string]$TargetDir)
+        # Try standard venv first
+        & $pythonCmd -m venv $TargetDir 2>$null
+        if ($LASTEXITCODE -eq 0) { return $true }
+
+        # Try uv venv if available (handles uv-managed Python)
+        if (Get-Command uv -ErrorAction SilentlyContinue) {
+            Write-Warning "Standard venv creation failed, trying uv venv..."
+            & uv venv $TargetDir 2>$null
+            if ($LASTEXITCODE -eq 0) {
+                # Bootstrap pip in uv venv
+                $venvPy = Join-Path $TargetDir "Scripts\python.exe"
+                $getPip = Join-Path $env:TEMP "get-pip.py"
+                Invoke-WebRequest -Uri "https://bootstrap.pypa.io/get-pip.py" -OutFile $getPip -ErrorAction SilentlyContinue
+                if (Test-Path $getPip) {
+                    & $venvPy $getPip 2>$null
+                    Remove-Item $getPip -ErrorAction SilentlyContinue
+                }
+                return $true
+            }
+        }
+        return $false
+    }
+
     if (Test-Path $VenvDir) {
         # Verify venv is valid
         $activateScript = Join-Path $VenvDir "Scripts\Activate.ps1"
@@ -724,13 +813,17 @@ function Setup-PythonEnv {
         } else {
             Write-Warning "Virtual environment is corrupted. Recreating..."
             Remove-Item -Recurse -Force $VenvDir
-            & $pythonCmd -m venv $VenvDir
-            Write-Success "Virtual environment recreated"
+            if (New-Venv -TargetDir $VenvDir) {
+                Write-Success "Virtual environment recreated"
+            } else {
+                Write-Error "Failed to create virtual environment"
+                Track-Failure -Category "critical" -Name "Python venv" -Reason "venv creation failed"
+                return
+            }
         }
     } else {
         Write-Info "Creating virtual environment at $VenvDir..."
-        & $pythonCmd -m venv $VenvDir
-        if ($LASTEXITCODE -eq 0) {
+        if (New-Venv -TargetDir $VenvDir) {
             Write-Success "Virtual environment created"
         } else {
             Write-Error "Failed to create virtual environment"
@@ -759,7 +852,8 @@ function Setup-PythonEnv {
     # Upgrade pip with prefer-binary
     Write-Info "Upgrading pip..."
     $pipLogFile = Join-Path $LogDir "pip-upgrade.log"
-    pip install --upgrade pip --prefer-binary 2>&1 | Tee-Object -FilePath $pipLogFile
+    $venvPython = Join-Path $VenvDir "Scripts\python.exe"
+    & $venvPython -m pip install --upgrade pip --prefer-binary 2>&1 | Tee-Object -FilePath $pipLogFile
     if ($LASTEXITCODE -eq 0) {
         Write-Success "pip upgraded successfully"
     } else {
@@ -1088,12 +1182,14 @@ function Show-Help {
     Write-Host "  .\install.ps1 [Options]"
     Write-Host ""
     Write-Host "Options:"
-    Write-Host "  -Y                 Skip all prompts and auto-confirm installation"
-    Write-Host "  -WithAdmin         Use admin-requiring package managers (chocolatey)"
-    Write-Host "  -Resume            Resume from previous interrupted installation"
-    Write-Host "  -RetryFailed       Retry previously failed packages"
-    Write-Host "  -SkipChocolatey    Skip Chocolatey installation (uses winget/scoop instead)"
-    Write-Host "  -Help              Show this help message"
+    Write-Host "  -Y                            Skip all prompts and auto-confirm installation"
+    Write-Host "  -WithAdmin                    Use admin-requiring package managers (chocolatey)"
+    Write-Host "  -Resume                       Resume from previous interrupted installation"
+    Write-Host "  -RetryFailed                  Retry previously failed packages"
+    Write-Host "  -SkipChocolatey               Skip Chocolatey installation (uses winget/scoop instead)"
+    Write-Host "  -PreferPackageManager <PM>    Prefer specific package manager (auto|winget|scoop|choco)"
+    Write-Host "                                Falls back to auto-detection if preferred PM unavailable"
+    Write-Host "  -Help                         Show this help message"
     Write-Host ""
     Write-Host "Exit Codes:"
     Write-Host "  0  Success (all dependencies installed)"
@@ -1101,10 +1197,12 @@ function Show-Help {
     Write-Host "  2  Partial success (some optional deps failed)"
     Write-Host ""
     Write-Host "Examples:"
-    Write-Host "  .\install.ps1                  # Normal install"
-    Write-Host "  .\install.ps1 -Y               # Non-interactive"
-    Write-Host "  .\install.ps1 -WithAdmin       # Use chocolatey if admin"
-    Write-Host "  .\install.ps1 -Resume          # Resume interrupted install"
+    Write-Host "  .\install.ps1                              # Normal install (auto-detect PM)"
+    Write-Host "  .\install.ps1 -PreferPackageManager scoop  # Prefer scoop, fallback to auto"
+    Write-Host "  .\install.ps1 -PreferPackageManager winget # Use winget explicitly"
+    Write-Host "  .\install.ps1 -Y                           # Non-interactive"
+    Write-Host "  .\install.ps1 -WithAdmin                   # Use chocolatey if admin"
+    Write-Host "  .\install.ps1 -Resume                      # Resume interrupted install"
     Write-Host ""
     Write-Host "Package Manager Priority:"
     Write-Host "  1. winget (recommended, no admin required)"
@@ -1128,8 +1226,11 @@ function Main {
     Write-Header "Claude Code Skills Installation (Windows)"
     Write-Info "Script directory: $ScriptDir"
 
+    # Store preference in script scope for functions to access
+    $Script:PreferPackageManager = $PreferPackageManager
+
     # Show detected package manager
-    $pm = Get-PackageManager
+    $pm = Get-PackageManager -Preference $PreferPackageManager
     if ($pm) {
         Write-Success "Detected package manager: $pm"
     } else {
@@ -1138,6 +1239,9 @@ function Main {
     }
 
     # Show mode info
+    if ($PreferPackageManager -ne "auto") {
+        Write-Info "Mode: prefer $PreferPackageManager (soft fallback to auto if unavailable)"
+    }
     if ($WithAdmin) {
         Write-Info "Mode: with admin (chocolatey enabled)"
     } else {