openapi.yaml

openapi: "3.1.0"
info:
  title: hawk-sdk-python — Python SDK API Reference
  description: |
    Python SDK for the hawk daemon HTTP API. Provides sync and async clients,
    SSE streaming, tool decorator, and workflow builder.

    This is a client SDK — it connects to the hawk daemon at http://localhost:4590.
    See hawk's api/openapi.yaml for the server-side contract.
  version: "0.1.0"
  license:
    name: MIT
    url: https://github.com/GrayCodeAI/hawk-sdk-python/blob/main/LICENSE
  contact:
    url: https://github.com/GrayCodeAI/hawk-sdk-python

servers:
  - url: http://localhost:4590
    description: Hawk daemon (managed by hawk, not this SDK)

x-sdk-api:
  package: hawk
  classes:
    - name: HawkClient
      description: Synchronous client
      constructor_args:
        base_url: string
        api_key: string
      methods:
        - health()
        - chat(message, **kwargs)
        - chat_stream(message, **kwargs)
        - list_sessions(limit, offset)
        - get_session(session_id)
        - delete_session(session_id)
        - get_session_messages(session_id, limit, offset)
        - stats()
    - name: AsyncHawkClient
      description: Asynchronous client (same methods with async/await)
    - name: Agent
      description: Higher-level conversation agent with session history
    - name: Workflow
      description: Multi-step workflow builder with retry config
  decorators:
    - name: tool
      description: Decorator to register a function as a hawk tool
      usage: "@tool()"