haijun-agent-sdk 0.1.0__tar.gz

haijun_agent_sdk-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+uv.lock
+
+# Local env files (live-backend test credentials etc.)
+.env
+.env.*
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+**/.DS_Store
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+htmlcov/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.ruff_cache/
+.haijun/worktrees/

haijun_agent_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JuGloW, PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

haijun_agent_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,405 @@
+Metadata-Version: 2.5
+Name: haijun-agent-sdk
+Version: 0.1.0
+Summary: Python SDK for Haijun Code via platform gateway
+Project-URL: Homepage, https://github.com/takebox/haijun-agent-sdk-python
+Project-URL: Documentation, https://raw.haijun.my.id/docs/en/docs/haijun-code/sdk
+Project-URL: Issues, https://github.com/takebox/haijun-agent-sdk-python/issues
+Author-email: JuGloW <support@juglow.my.id>
+License: MIT
+License-File: LICENSE
+Keywords: ai,haijun,juglow,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: jsonschema>=4.20.0
+Requires-Dist: mcp<3.0.0,>=1.23.0
+Requires-Dist: sniffio>=1.0.0
+Requires-Dist: typing-extensions>=4.0.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: anyio[trio]>=4.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: asyncpg>=0.27.0; extra == 'examples'
+Requires-Dist: boto3>=1.28.0; extra == 'examples'
+Requires-Dist: fakeredis>=2.20.0; extra == 'examples'
+Requires-Dist: moto[s3]>=5.0.0; extra == 'examples'
+Requires-Dist: redis>=4.2.0; extra == 'examples'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/haijun-logo.png" alt="Haijun" width="500">
+</p>
+
+<p align="center"><strong>Haijun Agent SDK for Python</strong> — Python SDK for Haijun Agent. See the [Haijun Agent SDK documentation](https://raw.haijun.my.id/docs/en/agent-sdk/python) for more information.
+
+## Installation
+
+```bash
+pip install haijun-agent-sdk
+```
+
+**Prerequisites:**
+
+- Python 3.10+
+
+**Note:** The Haijun Code CLI is automatically bundled with the package - no separate installation required! The SDK will use the bundled CLI by default. If you prefer to use a system-wide installation or a specific version, you can:
+
+- Install Haijun Code separately: `curl -fsSL https://downloads.haijun.my.id/cli/install.sh | bash`
+- Specify a custom path: `HaijunAgentOptions(cli_path="/path/to/haijun")`
+
+## Quick Start
+
+```python
+import anyio
+from haijun_agent_sdk import query
+
+async def main():
+    async for message in query(prompt="What is 2 + 2?"):
+        print(message)
+
+anyio.run(main)
+```
+
+## Basic Usage: query()
+
+`query()` is an async function for querying Haijun Code. It returns an `AsyncIterator` of response messages. See [src/haijun_agent_sdk/query.py](src/haijun_agent_sdk/query.py).
+
+```python
+from haijun_agent_sdk import query, HaijunAgentOptions, AssistantMessage, TextBlock
+
+# Simple query
+async for message in query(prompt="Hello Haijun"):
+    if isinstance(message, AssistantMessage):
+        for block in message.content:
+            if isinstance(block, TextBlock):
+                print(block.text)
+
+# With options
+options = HaijunAgentOptions(
+    system_prompt="You are a helpful assistant",
+    max_turns=1 )
+
+async for message in query(prompt="Tell me a joke", options=options):
+    print(message)
+```
+
+### Using Tools
+
+By default, Haijun has access to the full [Haijun Code toolset](https://raw.haijun.my.id/docs/en/settings#tools-available-to-haijun) (Read, Write, Edit, Bash, and others). `allowed_tools` is a permission allowlist: listed tools are auto-approved, and unlisted tools fall through to `permission_mode` and `can_use_tool` for a decision. It does not remove tools from Haijun's toolset. To block specific tools, use `disallowed_tools`. See the [permissions guide](https://raw.haijun.my.id/docs/en/agent-sdk/permissions) for the full evaluation order.
+
+```python
+options = HaijunAgentOptions(
+    allowed_tools=["Read", "Write", "Bash"],  # auto-approve these tools
+    permission_mode='acceptEdits'  # auto-accept file edits )
+
+async for message in query(
+    prompt="Create a hello.py file",
+    options=options ):
+    # Process tool use and results
+    pass
+```
+
+### Working Directory
+
+```python
+from pathlib import Path
+
+options = HaijunAgentOptions(
+    cwd="/path/to/project"  # or Path("/path/to/project")
+)
+```
+
+## HaijunSDKClient
+
+`HaijunSDKClient` supports bidirectional, interactive conversations with Haijun
+Code. See [src/haijun_agent_sdk/client.py](src/haijun_agent_sdk/client.py).
+
+Unlike `query()`, `HaijunSDKClient` additionally enables **custom tools** and **hooks**, both of which can be defined as Python functions.
+
+### Custom Tools (as In-Process SDK MCP Servers)
+
+A **custom tool** is a Python function that you can offer to Haijun, for Haijun to invoke as needed.
+
+Custom tools are implemented in-process MCP servers that run directly within your Python application, eliminating the need for separate processes that regular MCP servers require.
+
+For an end-to-end example, see [MCP Calculator](examples/mcp_calculator.py).
+
+#### Creating a Simple Tool
+
+```python
+from haijun_agent_sdk import tool, create_sdk_mcp_server, HaijunAgentOptions, HaijunSDKClient
+
+# Define a tool using the @tool decorator
+@tool("greet", "Greet a user", {"name": str})
+async def greet_user(args):
+    return {
+        "content": [
+            {"type": "text", "text": f"Hello, {args['name']}!"}
+        ]
+    }
+
+# Create an SDK MCP server
+server = create_sdk_mcp_server(
+    name="my-tools",
+    version="1.0.0",
+    tools=[greet_user]
+)
+
+# Use it with Haijun. allowed_tools pre-approves the tool so it runs
+# without a permission prompt; it does not control tool availability.
+options = HaijunAgentOptions(
+    mcp_servers={"tools": server},
+    allowed_tools=["mcp__tools__greet"]
+)
+
+async with HaijunSDKClient(options=options) as client:
+    await client.query("Greet Alice")
+
+    # Extract and print response
+    async for msg in client.receive_response():
+        print(msg)
+```
+
+#### Benefits Over External MCP Servers
+
+- **No subprocess management** - Runs in the same process as your application
+- **Better performance** - No IPC overhead for tool calls
+- **Simpler deployment** - Single Python process instead of multiple
+- **Easier debugging** - All code runs in the same process
+- **Type safety** - Direct Python function calls with type hints
+
+#### Migration from External Servers
+
+```python
+# BEFORE: External MCP server (separate process)
+options = HaijunAgentOptions(
+    mcp_servers={
+        "calculator": {
+            "type": "stdio",
+            "command": "python",
+            "args": ["-m", "calculator_server"]
+        }
+    }
+)
+
+# AFTER: SDK MCP server (in-process)
+from my_tools import add, subtract  # Your tool functions
+
+calculator = create_sdk_mcp_server(
+    name="calculator",
+    tools=[add, subtract]
+)
+
+options = HaijunAgentOptions(
+    mcp_servers={"calculator": calculator}
+)
+```
+
+#### Mixed Server Support
+
+You can use both SDK and external MCP servers together:
+
+```python
+options = HaijunAgentOptions(
+    mcp_servers={
+        "internal": sdk_server,      # In-process SDK server
+        "external": {                # External subprocess server
+            "type": "stdio",
+            "command": "external-server"
+        }
+    }
+)
+```
+
+### Hooks
+
+A **hook** is a Python function that the Haijun Code _application_ (_not_ Haijun) invokes at specific points of the Haijun agent loop. Hooks can provide deterministic processing and automated feedback for Haijun. Read more in [Intercept and control agent behavior with hooks](https://raw.haijun.my.id/docs/en/agent-sdk/hooks).
+
+For more examples, see examples/hooks.py.
+
+#### Example
+
+```python
+from haijun_agent_sdk import HaijunAgentOptions, HaijunSDKClient, HookMatcher
+
+async def check_bash_command(input_data, tool_use_id, context):
+    tool_name = input_data["tool_name"]
+    tool_input = input_data["tool_input"]
+    if tool_name != "Bash":
+        return {}
+    command = tool_input.get("command", "")
+    block_patterns = ["foo.sh"]
+    for pattern in block_patterns:
+        if pattern in command:
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": f"Command contains invalid pattern: {pattern}",
+                }
+            }
+    return {}
+
+options = HaijunAgentOptions(
+    allowed_tools=["Bash"],
+    hooks={
+        "PreToolUse": [
+            HookMatcher(matcher="Bash", hooks=[check_bash_command]),
+        ],
+    }
+)
+
+async with HaijunSDKClient(options=options) as client:
+    # Test 1: Command with forbidden pattern (will be blocked)
+    await client.query("Run the bash command: ./foo.sh --help")
+    async for msg in client.receive_response():
+        print(msg)
+
+    print("\n" + "=" * 50 + "\n")
+
+    # Test 2: Safe command that should work
+    await client.query("Run the bash command: echo 'Hello from hooks example!'")
+    async for msg in client.receive_response():
+        print(msg)
+```
+
+## Types
+
+See [src/haijun_agent_sdk/types.py](src/haijun_agent_sdk/types.py) for complete type definitions:
+
+- `HaijunAgentOptions` - Configuration options
+- `AssistantMessage`, `UserMessage`, `SystemMessage`, `ResultMessage` - Message types
+- `TextBlock`, `ToolUseBlock`, `ToolResultBlock` - Content blocks
+
+## Error Handling
+
+```python
+from haijun_agent_sdk import (
+    HaijunSDKError,      # Base error
+    CLINotFoundError,    # Haijun Code not installed
+    CLIConnectionError,  # Connection issues
+    ProcessError,        # Process failed
+    ResultError,         # Run ended with an error result (subclass of ProcessError)
+    CLIJSONDecodeError,  # JSON parsing issues )
+
+try:
+    async for message in query(prompt="Hello"):
+        pass
+except CLINotFoundError:
+    print("Please install Haijun Code")
+except ResultError as e:
+    # The CLI reported a terminal error result (also yielded as the final
+    # ResultMessage) and exited. Structured fields are on the exception.
+    print(f"Run failed: {e.subtype=} {e.terminal_reason=} {e.api_error_status=}")
+    print(e.result or e.errors)
+except ProcessError as e:
+    print(f"Process failed with exit code: {e.exit_code}")
+except CLIJSONDecodeError as e:
+    print(f"Failed to parse response: {e}")
+```
+
+See [src/haijun_agent_sdk/\_errors.py](src/haijun_agent_sdk/_errors.py) for all error types.
+
+## Available Tools
+
+See the [Haijun Code documentation](https://raw.haijun.my.id/docs/en/settings#tools-available-to-haijun) for a complete list of available tools.
+
+## Examples
+
+See [examples/quick_start.py](examples/quick_start.py) for a complete working example.
+
+See [examples/streaming_mode.py](examples/streaming_mode.py) for comprehensive examples involving `HaijunSDKClient`. You can even run interactive examples in IPython from [examples/streaming_mode_ipython.py](examples/streaming_mode_ipython.py).
+
+## Migrating from Haijun Code SDK
+
+If you're upgrading from the Haijun Code SDK (versions < 0.1.0), please see the [CHANGELOG.md](CHANGELOG.md#010) for details on breaking changes and new features, including:
+
+- `HaijunCodeOptions` → `HaijunAgentOptions` rename
+- Merged system prompt configuration
+- Settings isolation and explicit control
+- New programmatic subagents and session forking features
+
+## Development
+
+If you're contributing to this project, run the initial setup script to install git hooks:
+
+```bash
+./scripts/initial-setup.sh
+```
+
+This installs a pre-push hook that runs lint checks before pushing, matching the CI workflow. To skip the hook temporarily, use `git push --no-verify`.
+
+### Building Wheels Locally
+
+To build wheels with the bundled Haijun Code CLI:
+
+```bash
+# Install build dependencies
+pip install build twine
+
+# Build wheel with bundled CLI
+python scripts/build_wheel.py
+
+# Build with specific version
+python scripts/build_wheel.py --version 0.1.4
+
+# Build with specific CLI version
+python scripts/build_wheel.py --cli-version 2.0.0
+
+# Clean bundled CLI after building
+python scripts/build_wheel.py --clean
+
+# Skip CLI download (use existing)
+python scripts/build_wheel.py --skip-download
+```
+
+The build script:
+
+1. Downloads Haijun Code CLI for your platform
+2. Bundles it in the wheel
+3. Builds both wheel and source distribution
+4. Checks the package with twine
+
+See `python scripts/build_wheel.py --help` for all options.
+
+### Release Workflow
+
+The package is published to PyPI via the GitHub Actions workflow in `.github/workflows/publish.yml`. To create a new release:
+
+1. **Trigger the workflow** manually from the Actions tab with two inputs:
+   - `version`: The package version to publish (e.g., `0.1.5`)
+   - `haijun_code_version`: The Haijun Code CLI version to bundle (e.g., `2.0.0` or `latest`)
+
+2. **The workflow will**:
+   - Build platform-specific wheels for macOS, Linux, and Windows
+   - Bundle the specified Haijun Code CLI version in each wheel
+   - Build a source distribution
+   - Publish all artifacts to PyPI
+   - Create a release branch with version updates
+   - Open a PR to main with:
+     - Updated `pyproject.toml` version
+     - Updated `src/haijun_agent_sdk/_version.py`
+     - Updated `src/haijun_agent_sdk/_cli_version.py` with bundled CLI version
+     - Auto-generated `CHANGELOG.md` entry
+
+3. **Review and merge** the release PR to update main with the new version information
+
+The workflow tracks both the package version and the bundled CLI version separately, allowing you to release a new package version with an updated CLI without code changes.
+
+## License and terms
+
+Use of this SDK is governed by JuGloW's [Commercial Terms of Service](https://docs.juglow.my.id/legal/commercial-terms), including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license as indicated in that component's LICENSE file.