docs/CREATE_DRAFT_DOCUMENT.md

# create_draft_document Tool

## Overview

The `create_draft_document` tool allows users (both clients and lawyers) to create and save new document drafts directly to their "My Documents" storage in Supabase.

## Tool Specifications

### Facade Version (User-facing)

```python
@tool
async def create_draft_document(
    title: str,
    content: str,
    path: str
) -> str
```

**Parameters:**
- `title` (str): Document title (e.g., "Contract de bail", "Note juridique")
- `content` (str): Document content in HTML format (e.g., "<h1>Title</h1><p>Content...</p>")
- `path` (str): Folder path where to save the document
  - Empty string `""` → root folder of My Documents
  - `"Contracts/"` → ./Contracts/title.pdf
  - `"Drafts/Legal/"` → ./Drafts/Legal/title.pdf

**Returns:**
- Confirmation message with document path and success status

### Real Implementation (With user_id injection)

```python
@tool
async def _create_draft_document(
    user_id: str,
    title: str,
    content: str,
    path: str
) -> str
```

**Additional Parameter:**
- `user_id` (str): User UUID (automatically injected by the agent from state)

## Usage Examples

### Example 1: Save to root folder
```python
create_draft_document(
    title="Mon document",
    content="<h1>Document</h1><p>Contenu...</p>",
    path=""
)
# Saves as: ./Mon document.pdf
```

### Example 2: Save to Contracts folder
```python
create_draft_document(
    title="Contract de bail",
    content="<h1>Contrat de bail</h1><p>Ce contrat est conclu entre...</p>",
    path="Contracts/"
)
# Saves as: ./Contracts/Contract de bail.pdf
```

### Example 3: Save to nested folder
```python
create_draft_document(
    title="Note juridique",
    content="<h1>Note</h1><p>Contenu juridique...</p>",
    path="Drafts/Legal/"
)
# Saves as: ./Drafts/Legal/Note juridique.pdf
```

## Path Normalization Rules

The tool automatically normalizes the path:

1. Removes leading `./` if present
2. Ensures trailing `/` if path is provided
3. Adds `.pdf` extension automatically
4. Builds full path as `./{path}{title}.pdf`

| Input Path | Normalized Output |
|------------|-------------------|
| `"Contracts/"` | `"./Contracts/"` |
| `"Contracts"` | `"./Contracts/"` |
| `""` | `"./"` |
| `"./Contracts/"` | `"./Contracts/"` |
| `"Drafts/Legal/"` | `"./Drafts/Legal/"` |

## API Integration

### Supabase Endpoint

- **URL:** `{SUPABASE_BASE_URL}/create-document-from-html`
- **Method:** POST
- **Headers:**
  - `x-api-key: <CYBERLGL_API_KEY>`

### Request Body

```json
{
  "userId": "uuid-de-l-utilisateur",
  "html": "<h1>Document Title</h1><p>Content...</p>",
  "path": "./Contracts/Document Title.pdf"
}
```

### Response Handling

The tool handles different HTTP status codes:

- `200`: Success - Document saved
- `400`: Bad request - Returns error details
- `401`: Authentication failed - Invalid API key
- `403`: Access denied - No permission
- `500`: Server error

## Integration with Agents

### Toolsets

The tool is integrated into:

- **Client Tools:** `tools_for_client_facade` and `tools_for_client`
- **Lawyer Tools:** `tools_for_lawyer_facade` and `tools_for_lawyer`

### Parameter Injection

The `CyberLegalAgent` automatically injects `user_id` from the agent state when calling `_create_draft_document`:

```python
# In agents/chat_agent.py
if tool_call['name'] == "create_draft_document":
    args["user_id"] = state.get("user_id")
    logger.info(f"📝 Injecting user_id for create_draft_document: {args['user_id']}")
```

## Configuration Requirements

The following environment variables must be set:

- `SUPABASE_BASE_URL`: Base URL for Supabase functions
- `CYBERLGL_API_KEY`: API key for authentication

## Error Handling

The tool includes comprehensive error handling:

- Timeout errors (30s timeout)
- Connection errors
- JSON parsing errors
- HTTP status code errors
- Configuration errors (missing environment variables)

## Testing

A test file is available at `tests/test_create_draft_document.py` which tests:

1. Facade functionality
2. Real implementation with various path formats
3. Path normalization logic

## Use Cases

Users should use this tool when they want to:

- Create a new document draft
- Save a generated document
- Store a document in their document library
- Organize documents in specific folders

## Notes

- The `.pdf` extension is added automatically
- The path normalization is handled transparently
- The tool is available to both clients and lawyers
- The user_id is automatically injected and not exposed to users