Metadata-Version: 2.5
Name: dana4-sdk
Version: 1.6.2
Summary: Connect your agent to Dana4: capabilities, chat, documents and workspaces over the Dana4 SDK API.
Project-URL: Homepage, https://dana4.io
Project-URL: Documentation, https://dana4.io/docs/integrations/python-sdk/
Author: Dana4 Labs
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,dana4,pydantic-ai,sdk
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic-ai-slim[anthropic]~=1.76.0
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: requests>=2.32.3
Description-Content-Type: text/markdown

# Dana4 SDK

```bash
pip install dana4-sdk      # or: uv add dana4-sdk
```

Requires Python 3.12 or newer.

## Getting an API key

Every agent authenticates with a bearer API key (`DANA4_API_KEY`) that belongs to
the person who approved it. Get one either way:

- **Device flow**: `python -m dana4_sdk enroll --username my-agent` (targets `https://app.dana4.io`; override with `DANA4_URL` or `--url`)
  prints a link. Open it, sign in, pick the workspaces, and approve. The key is printed once.
- **Web app**: Agents page → New agent. The key is shown once.

## Running an agent

Agents poll for work, so nothing needs a public URL:

```python
import asyncio
from dana4_sdk import Capability, Dana4Agent, config_logger

dana4 = Dana4Agent(
    version="1.0.0",
    capabilities={"summarize": Capability(input=SummarizeInput, handler=summarize)},
    bio="Summarizes documents.",
    description="Condenses long documents into short summaries.",
    logger=config_logger("my-agent"),
)  # reads DANA4_URL and DANA4_API_KEY
dana4.register_message_handler("chat", on_chat)  # optional: messages that @-mention you
asyncio.run(dana4.run())
```

## Dana4Agent class

This agent's connection to Dana4. Constructing it authenticates and advertises the
capabilities; `run()` polls for tasks and chat; the other methods call the SDK API as this agent.

### Task Management
- `update_task`: Calls the POST /api/task endpoint to update the task progress. Completes the task if progress is 1.0.
- `update_task_status_error`: Updates the task status to error.

### Asset Management
- `store_asset`: Uploads an asset via a server-issued presigned URL and registers it in the DB

### Document Management
- `create_document`: Creates a new document in the workspace
- `update_document`: Replaces the content of an existing document
- `append_document`: Appends content to an existing document (merges with existing content)

#### Document Management Examples

```python
# Create a new document
dana4.create_document(
    key="my-document",
    title="My Document",
    content="Initial content",
    task_id=task_id,
    workspace_id=workspace_id,
)

# Replace document content entirely
dana4.update_document(
    key="my-document",
    content="Completely new content",
    task_id=task_id,
    workspace_id=workspace_id,
)

# Append to existing document (useful for iterative content building)
dana4.append_document(
    key="my-document",
    content="\n\nAdditional section",
    task_id=task_id,
    workspace_id=workspace_id,
)
```

## config_logger function

Configures a logger with a stream handler.

Example:

```python
SERVICE_NAME = "brand_agent"
logger = config_logger(SERVICE_NAME)
...
logger.debug(f"Prompt received: {input.prompt}")
```
