Metadata-Version: 2.4
Name: humanizedtext
Version: 0.1.1
Summary: Official Python SDK for HumanizedText API
Author: HumanizedText
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

# humanizedtext (Python)

Official Python SDK for the HumanizedText API.

This SDK provides a simple interface over HumanizedText authenticated SDK endpoints:

- Humanize text with optional tone/keywords/ultra mode
- Fix grammar
- Rewrite content
- Generate SEO blog drafts

## Contents

1. Requirements
2. Installation
3. Authentication
4. Client Configuration
5. API Methods
6. Response Examples
7. Error Handling
8. Edge Cases and Limits
9. Production Recommendations

## Requirements

- Python `>=3.9`
- A valid HumanizedText API key

## Installation

```bash
pip install humanizedtext
```

## Authentication

The client sends your API key in `X-API-Key` header on each request.

```python
import os
from humanizedtext import HumanizedTextClient

client = HumanizedTextClient(api_key=os.environ["HUMANIZEDTEXT_API_KEY"])
```

## Client Configuration

```python
from humanizedtext import HumanizedTextClient

client = HumanizedTextClient(
    api_key="YOUR_API_KEY",
    base_url="https://api.humanizedtext.pro/api/v1",
    timeout=60,
)
```

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `api_key` | `str` | Yes | - | HumanizedText API key |
| `base_url` | `str` | No | `https://api.humanizedtext.pro/api/v1` | API base URL |
| `timeout` | `int` | No | `60` | Request timeout in seconds |

## API Methods

### 1) `humanize(text, tone=None, ultra_humanize=False, keywords=None)`

Humanizes text with optional tone and keyword assistance.

```python
response = client.humanize(
    text="Your AI-like draft",
    tone="professional",
    ultra_humanize=False,
    keywords=["SaaS", "conversion"],
)
```

| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| `text` | `str` | Yes | - | Must be `1..6000` chars |
| `tone` | `Optional[str]` | No | `None` | Example: `professional`, `casual`, `friendly`, `default` |
| `ultra_humanize` | `bool` | No | `False` | Consumes ultra quota when `True` |
| `keywords` | `Optional[List[str]]` | No | `None` | Plan-limited keyword count per request |

### 2) `grammar_fixer(text)`

Fixes grammar while preserving message.

```python
response = client.grammar_fixer("this are a sentence.")
```

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `text` | `str` | Yes | Must be `1..6000` chars |

### 3) `content_rewriter(text)`

Rewrites content to improve readability/originality.

```python
response = client.content_rewriter("Original paragraph here")
```

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `text` | `str` | Yes | Must be `1..6000` chars |

### 4) `seo_blog_writer(topic)`

Generates SEO-focused article content from a topic.

```python
response = client.seo_blog_writer("Best CRM tools for startups")
```

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `topic` | `str` | Yes | Must be `1..500` chars |

## Response Examples

The SDK returns parsed JSON (`dict`) from API.

### Humanize response

```python
{
    "original_text": "Your original text",
    "humanized_text": "Humanized output text",
    "tone_applied": "professional",
    "ultra_humanize_used": False,
    "keywords_used": ["SaaS", "conversion"],
    "created_at": "2026-04-12T15:20:11.891000+00:00"
}
```

### Grammar fixer response

```python
{
    "original_text": "this are a sentence.",
    "corrected_text": "This is a sentence.",
    "created_at": "2026-04-12T15:21:17.003000+00:00"
}
```

### Content rewriter response

```python
{
    "original_text": "Old copy here",
    "rewritten_text": "Rewritten copy here",
    "created_at": "2026-04-12T15:22:40.221000+00:00"
}
```

### SEO blog writer response

```python
{
    "topic": "Best CRM tools for startups",
    "blog_content": "# Best CRM tools for startups\n...",
    "created_at": "2026-04-12T15:23:35.552000+00:00"
}
```

## Error Handling

HTTP failures raise `HumanizedTextAPIError`.

```python
from humanizedtext import HumanizedTextClient
from humanizedtext_sdk.exceptions import HumanizedTextAPIError

client = HumanizedTextClient(api_key="YOUR_API_KEY")

try:
    client.humanize(text="")
except HumanizedTextAPIError as exc:
    print("status:", exc.status_code)
    print("payload:", exc.payload)
    print("message:", str(exc))
```

`HumanizedTextAPIError` fields:

| Field | Type | Description |
|---|---|---|
| `status_code` | `int \| None` | HTTP status code |
| `payload` | `Any` | Parsed response body or fallback text payload |
| `message` | `str` | Human-readable error detail |

## Edge Cases and Limits

### Validation failures (`400`)

- Empty `text`/`topic`
- `text` over 6000 chars
- `topic` over 500 chars
- Too many `keywords` for your plan

Possible keyword-limit error shape:

```python
{
    "message": "Keyword limit exceeded",
    "max_keywords_allowed": 1,
    "keywords_provided": 3,
    "upgrade_required": True
}
```

### Auth failures (`401`)

- Missing/invalid API key

### Character limit exceeded (`402`)

Possible error detail object:

```python
{
    "message": "SDK character limit exceeded for current period",
    "plan": "free",
    "characters_needed": 1200,
    "remaining_characters": 0,
    "period_resets_at": "2026-04-30T00:00:00+00:00"
}
```

### Rate/ultra limits (`429`)

- Too many requests
- Ultra humanize quota exceeded for current period

### Processing errors (`500`)

- Upstream generation failure
- Temporary backend processing issue

## Production Recommendations

- Keep API keys in environment variables.
- Add retry/backoff for transient 5xx and network errors.
- Log `status_code` and `payload` from exceptions for diagnostics.
- Validate payload size before request to prevent avoidable 400 errors.

## Legacy Import Compatibility

Primary import:

```python
from humanizedtext import HumanizedTextClient
```

Backward-compatible module also exists:

```python
from humanizedtext_sdk import HumanizedTextClient
```

## License

MIT
