greennode-agentbase 1.0.1__tar.gz

greennode_agentbase-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,272 @@
+name: Publish Package
+
+on:
+  push:
+    branches:
+      - dev
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish-dev:
+    name: Publish Dev Version to TestPyPI
+    runs-on: ubuntu-latest
+    permissions: 
+      id-token: write
+      contents: read
+    if: github.ref == 'refs/heads/dev' && github.event_name == 'push'
+    environment:
+          name: testpypi
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install hatch
+        run: pip install hatch
+
+      - name: Inject Multiple Configs
+        env:
+          IDENTITY_CONFIG: ${{ secrets.IDENTITY_CONFIG }}
+          RUNTIME_CONFIG: ${{ secrets.RUNTIME_CONFIG }}
+          MEMORY_CONFIG: ${{ secrets.MEMORY_CONFIG }}
+        run: |
+          echo -n "$IDENTITY_CONFIG" | base64 --decode > src/greennode_agentbase/specs/identity/api.json.gz
+          echo -n "$RUNTIME_CONFIG" | base64 --decode > src/greennode_agentbase/specs/runtime/api.json.gz
+          echo -n "$MEMORY_CONFIG" | base64 --decode > src/greennode_agentbase/specs/memory/api.json.gz
+
+      - name: Verify Files Exist
+        run: |
+          ls -l src/greennode_agentbase/specs/identity/api.json.gz
+          ls -l src/greennode_agentbase/specs/runtime/api.json.gz
+          ls -l src/greennode_agentbase/specs/memory/api.json.gz
+    
+          if [ ! -s src/greennode_agentbase/specs/identity/api.json.gz ]; then
+            echo "Error: Identity config is empty!"
+            exit 1
+          fi
+
+      - name: Extract base version from pyproject.toml
+        id: get_version
+        run: |
+          python << PYTHON_SCRIPT
+          import os
+          import sys
+          try:
+              import tomllib
+              with open('pyproject.toml', 'rb') as f:
+                  data = tomllib.load(f)
+                  version = data['project']['version']
+          except ImportError:
+              import tomli
+              with open('pyproject.toml', 'rb') as f:
+                  data = tomli.load(f)
+                  version = data['project']['version']
+          output_file = os.environ['GITHUB_OUTPUT']
+          with open(output_file, 'a') as f:
+              f.write(f'base_version={version}\n')
+          PYTHON_SCRIPT
+
+      - name: Generate dev version
+        id: dev_version
+        run: |
+          TIMESTAMP=$(date -u +%Y%m%d%H%M%S)
+          DEV_VERSION="${{ steps.get_version.outputs.base_version }}dev-$TIMESTAMP"
+          echo "version=$DEV_VERSION" >> $GITHUB_OUTPUT
+          echo "Generated dev version: $DEV_VERSION"
+
+      - name: Update pyproject.toml with dev version
+        run: |
+          python << EOF
+          import re
+          with open('pyproject.toml', 'r') as f:
+              content = f.read()
+          content = re.sub(
+              r'^version = ".*"',
+              f'version = "${{ steps.dev_version.outputs.version }}"',
+              content,
+              flags=re.MULTILINE
+          )
+          with open('pyproject.toml', 'w') as f:
+              f.write(content)
+          EOF
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          repository-url: https://test.pypi.org/legacy/
+
+  test-publish:
+    name: Verify on TestPyPI
+    runs-on: ubuntu-latest
+    environment: testpypi  
+    permissions:
+      id-token: write
+      contents: read
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install hatch
+        run: pip install hatch
+
+      - name: Inject Multiple Configs
+        env:
+          IDENTITY_CONFIG: ${{ secrets.IDENTITY_CONFIG }}
+          RUNTIME_CONFIG: ${{ secrets.RUNTIME_CONFIG }}
+          MEMORY_CONFIG: ${{ secrets.MEMORY_CONFIG }}
+        run: |
+          echo -n "$IDENTITY_CONFIG" | base64 --decode > src/greennode_agentbase/specs/identity/api.json.gz
+          echo -n "$RUNTIME_CONFIG" | base64 --decode > src/greennode_agentbase/specs/runtime/api.json.gz
+          echo -n "$MEMORY_CONFIG" | base64 --decode > src/greennode_agentbase/specs/memory/api.json.gz
+
+      - name: Verify Files Exist
+        run: |
+          ls -l src/greennode_agentbase/specs/identity/api.json.gz
+          ls -l src/greennode_agentbase/specs/runtime/api.json.gz
+          ls -l src/greennode_agentbase/specs/memory/api.json.gz
+    
+          if [ ! -s src/greennode_agentbase/specs/identity/api.json.gz ]; then
+            echo "Error: Identity config is empty!"
+            exit 1
+          fi
+
+      - name: Extract version from tag
+        id: get_tag_version
+        run: |
+          if [[ "${{ github.ref }}" =~ ^refs/tags/v(.+)$ ]]; then
+            TAG_VERSION="${BASH_REMATCH[1]}"
+          else
+            TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          fi
+          echo "version=$TAG_VERSION" >> $GITHUB_OUTPUT
+          echo "Extracted version from tag: $TAG_VERSION"
+
+      - name: Update pyproject.toml with tag version
+        run: |
+          python << EOF
+          import re
+          with open('pyproject.toml', 'r') as f:
+              content = f.read()
+          content = re.sub(
+              r'^version = ".*"',
+              f'version = "${{ steps.get_tag_version.outputs.version }}"',
+              content,
+              flags=re.MULTILINE
+          )
+          with open('pyproject.toml', 'w') as f:
+              f.write(content)
+          EOF
+
+      - name: Build package
+        run: hatch build
+      
+      - name: Verify Package Contents (Crucial)
+        run: |
+          echo "Checking for json.gz in the built wheel..."
+          unzip -l dist/*.whl | grep "json.gz"
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-release:
+    name: Publish Release to PyPI
+    needs: test-publish
+    runs-on: ubuntu-latest
+    permissions: 
+      id-token: write
+      contents: read
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+          name: pypi
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install hatch
+        run: pip install hatch
+
+      - name: Inject Multiple Configs
+        env:
+          IDENTITY_CONFIG: ${{ secrets.IDENTITY_CONFIG }}
+          RUNTIME_CONFIG: ${{ secrets.RUNTIME_CONFIG }}
+          MEMORY_CONFIG: ${{ secrets.MEMORY_CONFIG }}
+        run: |
+          echo -n "$IDENTITY_CONFIG" | base64 --decode > src/greennode_agentbase/specs/identity/api.json.gz
+          echo -n "$RUNTIME_CONFIG" | base64 --decode > src/greennode_agentbase/specs/runtime/api.json.gz
+          echo -n "$MEMORY_CONFIG" | base64 --decode > src/greennode_agentbase/specs/memory/api.json.gz
+
+      - name: Verify Files Exist
+        run: |
+          ls -l src/greennode_agentbase/specs/identity/api.json.gz
+          ls -l src/greennode_agentbase/specs/runtime/api.json.gz
+          ls -l src/greennode_agentbase/specs/memory/api.json.gz
+    
+          if [ ! -s src/greennode_agentbase/specs/identity/api.json.gz ]; then
+            echo "Error: Identity config is empty!"
+            exit 1
+          fi
+
+      - name: Extract version from tag
+        id: get_tag_version
+        run: |
+          if [[ "${{ github.ref }}" =~ ^refs/tags/v(.+)$ ]]; then
+            TAG_VERSION="${BASH_REMATCH[1]}"
+          else
+            TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          fi
+          echo "version=$TAG_VERSION" >> $GITHUB_OUTPUT
+          echo "Extracted version from tag: $TAG_VERSION"
+
+      - name: Update pyproject.toml with tag version
+        run: |
+          python << EOF
+          import re
+          with open('pyproject.toml', 'r') as f:
+              content = f.read()
+          content = re.sub(
+              r'^version = ".*"',
+              f'version = "${{ steps.get_tag_version.outputs.version }}"',
+              content,
+              flags=re.MULTILINE
+          )
+          with open('pyproject.toml', 'w') as f:
+              f.write(content)
+          EOF
+
+      - name: Build package
+        run: hatch build
+      
+      - name: Verify Package Contents (Crucial)
+        run: |
+          echo "Checking for json.gz in the built wheel..."
+          unzip -l dist/*.whl | grep "json.gz"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+        

greennode_agentbase-1.0.1/.gitignore

@@ -0,0 +1,3 @@
+src/greennode_agentbase/specs/runtime/api.json.gz
+src/greennode_agentbase/specs/identity/api.json.gz
+src/greennode_agentbase/specs/memory/api.json.gz

greennode_agentbase-1.0.1/PKG-INFO

@@ -0,0 +1,367 @@
+Metadata-Version: 2.4
+Name: greennode-agentbase
+Version: 1.0.1
+Summary: An SDK for building and deploying AI agents with GreenNode AgentBase
+Project-URL: Homepage, https://git.vngcloud.tech/cloud-ai-platform/greennode-agent-base-sdk
+Project-URL: Bug Tracker, https://git.vngcloud.tech/cloud-ai-platform/greennode-agent-base-sdk/issues
+Project-URL: Documentation, https://git.vngcloud.tech/cloud-ai-platform/greennode-agent-base-sdk
+Author-email: GreenNode <opensource@greennode.ai>
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Requires-Dist: click>=8.0.0
+Requires-Dist: docker>=6.0.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic<2.41.3,>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: starlette>=0.46.2
+Requires-Dist: typing-extensions<5.0.0,>=4.13.2
+Requires-Dist: uvicorn>=0.34.2
+Description-Content-Type: text/markdown
+
+# GreenNode AgentBase SDK
+
+A Python SDK for building and deploying AI agents with GreenNode AgentBase runtime.
+
+## Overview
+
+GreenNode AgentBase SDK provides a runtime framework for deploying AI agents with support for:
+- HTTP endpoint handling for agent invocations
+- Health status monitoring and ping endpoints
+- Async task tracking
+- Request context management
+- Streaming responses
+- Unified error handling
+
+## Installation
+
+```bash
+pip install greennode-agentbase
+```
+
+## Quick Start
+
+```python
+from greennode_agentbase import GreenNodeAgentBaseApp
+
+# Create the application
+app = GreenNodeAgentBaseApp()
+
+# Define your agent handler
+@app.entrypoint
+def my_agent(payload: dict):
+    """Your agent logic here."""
+    query = payload.get("query", "")
+    # Process the query with your agent
+    return {"response": f"Processed: {query}"}
+
+# Run the server
+if __name__ == "__main__":
+    app.run(port=8080)
+```
+
+## Usage
+
+### Basic Agent Handler
+
+```python
+from greennode_agentbase import GreenNodeAgentBaseApp
+
+app = GreenNodeAgentBaseApp()
+
+@app.entrypoint
+def simple_agent(payload: dict) -> dict:
+    """Simple agent that echoes the input."""
+    return {"echo": payload}
+```
+
+### Handler with Request Context
+
+```python
+from greennode_agentbase import GreenNodeAgentBaseApp, RequestContext
+
+app = GreenNodeAgentBaseApp()
+
+@app.entrypoint
+def contextual_agent(payload: dict, context: RequestContext) -> dict:
+    """Agent that uses request context."""
+    session_id = context.session_id
+    headers = context.request_headers or {}
+    
+    return {
+        "result": payload,
+        "session_id": session_id,
+        "authorization": headers.get("Authorization"),
+    }
+```
+
+### Async Agent Handler
+
+```python
+import asyncio
+from greennode_agentbase import GreenNodeAgentBaseApp
+
+app = GreenNodeAgentBaseApp()
+
+@app.entrypoint
+async def async_agent(payload: dict) -> dict:
+    """Async agent handler."""
+    # Simulate async work
+    await asyncio.sleep(0.1)
+    return {"result": "async processing complete"}
+```
+
+### Streaming Responses
+
+```python
+from greennode_agentbase import GreenNodeAgentBaseApp
+
+app = GreenNodeAgentBaseApp()
+
+@app.entrypoint
+def streaming_agent(payload: dict):
+    """Agent that streams responses."""
+    for i in range(5):
+        yield {"chunk": i, "data": f"chunk_{i}"}
+```
+
+### Custom Ping Handler
+
+```python
+from greennode_agentbase import GreenNodeAgentBaseApp, PingStatus
+
+app = GreenNodeAgentBaseApp()
+
+@app.ping
+def custom_health_check() -> PingStatus:
+    """Custom health check logic."""
+    # Check your system health
+    if system_is_busy():
+        return PingStatus.HEALTHY_BUSY
+    return PingStatus.HEALTHY
+```
+
+### Async Task Tracking
+
+```python
+from greennode_agentbase import GreenNodeAgentBaseApp
+
+app = GreenNodeAgentBaseApp()
+
+@app.async_task
+async def background_processing():
+    """Long-running background task."""
+    # This task will be tracked for health monitoring
+    await process_large_dataset()
+```
+
+### Error Handling
+
+All SDK errors inherit from `GreenNodeAgentBaseError`:
+
+```python
+from greennode_agentbase import (
+    GreenNodeAgentBaseError,
+    GreenNodeValidationError,
+    GreenNodeRuntimeError,
+    GreenNodeRequestError,
+    GreenNodeConfigurationError,
+)
+
+try:
+    # Your code here
+    pass
+except GreenNodeValidationError as e:
+    print(f"Validation error: {e.message}")
+    print(f"Details: {e.details}")
+except GreenNodeRuntimeError as e:
+    print(f"Runtime error: {e.message}")
+except GreenNodeAgentBaseError as e:
+    print(f"SDK error: {e.message}")
+```
+
+## Command-line interface (CLI)
+
+The `greennode` CLI provides deploy, memory, and runtime management. Use `greennode --help` and `greennode <group> --help` for details.
+
+### CLI hierarchy
+
+```text
+greennode
+├── deploy
+│   └── run              Deploy agent (build, push, create runtime). Use -o id to print only the runtime id.
+├── memory
+│   ├── create           Create a memory
+│   ├── list             List memories
+│   ├── get              Get a memory by ID
+│   └── ...              (other memory subcommands)
+└── runtime
+    ├── list             List runtimes
+    ├── get <id>         Get a runtime by ID
+    ├── patch <id>       Update a runtime (image, flavor, env, command, args)
+    └── endpoints
+        ├── list <runtime-id>     List endpoints for a runtime
+        ├── create <runtime-id>   Create an endpoint
+        ├── update <runtime-id> <endpoint-id>   Update endpoint (e.g. --version)
+        └── delete <runtime-id> <endpoint-id>  Delete an endpoint
+```
+
+### Best practices
+
+- **Config precedence:** Values are resolved in order: environment variables → `.greennode.json` (for `GREENNODE_CLIENT_ID`, `GREENNODE_CLIENT_SECRET`, `GREENNODE_ACCESS_CONTROL_NAME`, registry vars, etc.). Use `.greennode.json` for non-sensitive defaults and environment variables for secrets.
+- **When to use which:** Use `greennode deploy run` for a full deploy (build, push, create runtime). Use `greennode runtime list`, `get`, `patch` and `greennode runtime endpoints ...` to manage runtimes and endpoints without redeploying.
+- **Scripting:** After `greennode deploy run`, the runtime id is printed on its own line. Use `greennode deploy run -o id` to print only the runtime id for scripts.
+
+## API Reference
+
+### GreenNodeAgentBaseApp
+
+Main application class for deploying agents.
+
+#### Methods
+
+- `entrypoint(func)` - Decorator to register the main agent handler
+- `ping(func)` - Decorator to register a custom ping/health handler
+- `async_task(func)` - Decorator to track async tasks
+- `run(port=8080, host=None)` - Start the server
+- `get_current_ping_status()` - Get current health status
+- `force_ping_status(status)` - Force a specific ping status
+- `add_async_task(name, metadata=None)` - Manually track an async task
+- `complete_async_task(task_id)` - Mark an async task as complete
+
+### RequestContext
+
+Request context model containing request metadata.
+
+#### Attributes
+
+- `session_id` - Optional session identifier
+- `request_headers` - Optional dictionary of request headers
+- `request` - Underlying Starlette request object
+
+### GreenNodeAgentBaseContext
+
+Context manager for request-scoped data.
+
+#### Methods
+
+- `set_request_context(request_id, session_id=None)` - Set request context
+- `get_request_id()` - Get current request ID
+- `get_session_id()` - Get current session ID
+- `set_workload_access_token(token)` - Set access token
+- `get_workload_access_token()` - Get access token
+- `set_request_headers(headers)` - Set request headers
+- `get_request_headers()` - Get request headers
+
+### PingStatus
+
+Enum for health status values:
+
+- `HEALTHY` - Agent is healthy and ready
+- `HEALTHY_BUSY` - Agent is healthy but processing requests
+
+## HTTP Endpoints
+
+### POST /invocations
+
+Main endpoint for agent invocations.
+
+**Request:**
+```json
+{
+  "prompt": "your input here"
+}
+```
+
+**Response:**
+```json
+{
+  "result": "agent output"
+}
+```
+
+### GET /health
+
+Health check endpoint.
+
+**Response:**
+```json
+{
+  "status": "Healthy",
+  "time_of_last_update": 1234567890
+}
+```
+
+## Error Handling
+
+All errors in the SDK inherit from `GreenNodeAgentBaseError`:
+
+- `GreenNodeValidationError` - Input validation errors
+- `GreenNodeRuntimeError` - Runtime execution errors
+- `GreenNodeConfigurationError` - Configuration errors
+- `GreenNodeRequestError` - HTTP request errors
+
+All errors include:
+- `message` - Error message
+- `details` - Optional error details dictionary
+- `cause` - Optional underlying exception
+
+## Development
+
+### Setup
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linting
+ruff check src tests
+
+# Run type checking
+mypy src
+```
+
+### Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src --cov-report=html
+
+# Run specific test file
+pytest tests/greennode_agentbase/runtime/test_app.py
+```
+
+## License
+
+Apache License 2.0 - see [LICENSE.txt](LICENSE.txt) for details.
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+- All tests pass
+- Code follows the style guidelines (ruff, mypy)
+- New features include tests
+- Documentation is updated
+
+## Support
+
+For issues and questions, please use the project's issue tracker.