# SemanticPen Python SDK
[](https://badge.fury.io/py/semanticpen)
[](https://pypi.org/project/semanticpen/)
[](https://opensource.org/licenses/MIT)
**AI Article Writer & SEO Blog Generator SDK** - Professional Python library for automated content creation, AI-powered article generation, and SEO blog writing with [SemanticPen](https://www.semanticpen.com).
## 🚀 Features
- **AI-Powered Article Generation**: Generate high-quality articles from keywords
- **SEO Optimization**: Built-in SEO best practices and optimization
- **Bulk Operations**: Generate multiple articles simultaneously
- **Real-time Status Tracking**: Monitor article generation progress
- **Type Safety**: Full typing support with dataclasses and type hints
- **Error Handling**: Comprehensive error handling and retry mechanisms
- **Async Support**: Built for high-performance applications
- **Flexible Configuration**: Customizable settings for different use cases
## 📦 Installation
```bash
pip install semanticpen
```
## 🔑 Quick Start
### Basic Usage
```python
from semanticpen import SemanticPenClient
# Initialize client
client = SemanticPenClient.create("your-api-key")
# Generate a single article
result = client.generate_article("Python programming best practices")
print(f"Article ID: {result['articleId']}")
print(f"Project ID: {result['projectId']}")
print(f"Message: {result['message']}")
# Check article status
status = client.get_article_status(result['articleId'])
print(f"Status: {status['status']}")
print(f"Complete: {status['isComplete']}")
```
### Advanced Configuration
```python
from semanticpen import SemanticPenClient, SemanticPenConfig
# Custom configuration
config = SemanticPenConfig(
api_key="your-api-key",
base_url="https://www.semanticpen.com",
timeout=60000, # 60 seconds
debug=True
)
client = SemanticPenClient.create_with_config(config)
```
## 📝 Core Features
### 1. Article Generation
#### Single Article
```python
# Simple generation
result = client.generate_article("AI in healthcare")
# With options
result = client.generate_article(
"Machine learning algorithms",
gpt_version="gpt-4",
project_name="AI Blog Series",
preset_id="seo-optimized"
)
```
#### Bulk Generation
```python
keywords = [
"Python web development",
"Django best practices",
"FastAPI tutorial"
]
results = client.generate_articles(keywords)
print(f"Successfully generated: {results.success_count}")
print(f"Failed: {results.failure_count}")
```
### 2. Article Retrieval
```python
# Get complete article
article = client.get_article("article-id")
print(f"Title: {article.title}")
print(f"Content: {article.article_html}")
print(f"Status: {article.status}")
# Get multiple articles
article_ids = ["id1", "id2", "id3"]
results = client.get_articles(article_ids)
for article in results.successful:
print(f"Article: {article.title}")
```
### 3. Status Monitoring
```python
# Quick completion check
is_complete = client.is_article_complete("article-id")
# Detailed status
status = client.get_article_status("article-id")
print(f"Status: {status['status']}")
print(f"Complete: {status['isComplete']}")
print(f"Has Error: {status['hasError']}")
```
### 4. Waiting for Completion
```python
from semanticpen import PollingConfig
# Generate and wait for completion
article = client.generate_and_wait(
"Content marketing strategies",
polling_config=PollingConfig(
interval=5000, # Check every 5 seconds
max_attempts=60 # Max 5 minutes
)
)
print(f"Completed article: {article.title}")
print(f"Content length: {len(article.article_html)}")
```
### 5. Bulk Operations with Progress Tracking
```python
def progress_callback(completed, total, new_articles):
print(f"Progress: {completed}/{total} articles completed")
for article in new_articles:
print(f" ✓ {article.title}")
# Generate multiple articles and wait
result = client.generate_bulk_and_wait(
["Topic 1", "Topic 2", "Topic 3"],
on_progress=progress_callback
)
print(f"Successful: {len(result['successful'])}")
print(f"Failed: {len(result['failed'])}")
print(f"Total time: {result['total_time']:.2f} seconds")
```
## 🏗️ Advanced Usage
### Request Builder Pattern
```python
# Complex article generation with builder pattern
builder = client.create_request_builder()
articles = (builder
.keyword(["AI ethics", "Machine learning bias"])
.gpt_version("gpt-4")
.project_name("AI Ethics Series")
.preset("academic")
.parameter("tone", "professional")
.parameter("target_audience", "researchers")
.generate_and_wait())
print(f"Generated {len(articles)} articles")
```
### Error Handling
```python
from semanticpen import (
AuthenticationError,
ValidationError,
RateLimitError,
NetworkError,
TimeoutError
)
try:
result = client.generate_article("Python tutorials")
except AuthenticationError:
print("Invalid API key")
except ValidationError as e:
print(f"Invalid input: {e}")
except RateLimitError as e:
print(f"Rate limit exceeded. Retry after: {e.retry_after}s")
except NetworkError:
print("Network connection failed")
except TimeoutError:
print("Request timed out")
```
### Custom Polling Configuration
```python
from semanticpen import PollingConfig
# Custom polling behavior
custom_polling = PollingConfig(
interval=3000, # Poll every 3 seconds
max_attempts=100, # Try for up to 100 times
backoff_multiplier=1.2 # Increase interval by 20% each time
)
article = client.wait_for_article(
"article-id",
polling_config=custom_polling
)
```
## 🔧 Configuration Options
### SemanticPenConfig
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | Required | Your SemanticPen API key |
| `base_url` | `str` | `"https://www.semanticpen.com"` | API base URL |
| `timeout` | `int` | `30000` | Request timeout in milliseconds |
| `debug` | `bool` | `False` | Enable debug logging |
### PollingConfig
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `interval` | `int` | `5000` | Polling interval in milliseconds |
| `max_attempts` | `int` | `60` | Maximum polling attempts |
| `backoff_multiplier` | `float` | `1.0` | Exponential backoff multiplier |
## 📊 Response Types
### Article
```python
@dataclass
class Article:
id: str
organization_id: str
user_id: str
project_id: str
target_keyword: str
status: ArticleStatusEnum
created_at: str
updated_at: str
article_html: Optional[str] = None
content: Optional[str] = None
title: Optional[str] = None
metadata: Optional[Dict[str, Any]] = None
completed_at: Optional[str] = None
error_message: Optional[str] = None
```
### BulkOperationResult
```python
@dataclass
class BulkOperationResult:
successful: List[Any]
failed: List[Dict[str, Any]]
total: int
success_count: int
failure_count: int
```
## 🧪 Testing
```python
# Test API connection
if client.test_connection():
print("✓ Connected to SemanticPen API")
else:
print("✗ Connection failed")
# Validate keywords
validation = SemanticPenClient.validate_keywords([
"Valid keyword",
"", # Invalid
"Another valid keyword"
])
if validation["valid"]:
print("All keywords are valid")
else:
print(f"Validation errors: {validation['errors']}")
```
## 📚 API Reference
### SemanticPenClient Methods
| Method | Description |
|--------|-------------|
| `create(api_key, **options)` | Create client with API key |
| `test_connection()` | Test API connectivity |
| `generate_article(keyword, **options)` | Generate single article |
| `generate_articles(keywords, **options)` | Generate multiple articles |
| `get_article(article_id)` | Retrieve article by ID |
| `get_articles(article_ids)` | Retrieve multiple articles |
| `is_article_complete(article_id)` | Check if article is complete |
| `get_article_status(article_id)` | Get article status |
| `wait_for_article(article_id, **options)` | Wait for article completion |
| `generate_and_wait(keyword, **options)` | Generate and wait workflow |
## 🌟 Examples
See the [`examples/`](./examples) directory for complete examples:
- [`basic_usage.py`](./examples/basic_usage.py) - Simple article generation
- [`bulk_generation.py`](./examples/bulk_generation.py) - Multiple article generation
- [`async_monitoring.py`](./examples/async_monitoring.py) - Real-time status monitoring
- [`error_handling.py`](./examples/error_handling.py) - Comprehensive error handling
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- **Website**: [https://www.semanticpen.com](https://www.semanticpen.com)
- **API Documentation**: [https://www.semanticpen.com/api-documentation](https://www.semanticpen.com/api-documentation)
- **Python SDK Documentation**: [https://www.semanticpen.com/api-documentation](https://www.semanticpen.com/api-documentation)
- **Support**: [contact@semanticpen.com](mailto:contact@semanticpen.com)
- **Issues**: [GitHub Issues](https://github.com/semanticpen/python-sdk/issues)
## 💡 Need Help?
- 📖 Check our [documentation](https://www.semanticpen.com/api-documentation)
- 💬 Join our [community forum](https://community.semanticpen.com)
- 📧 Email us at [support@semanticpen.com](mailto:support@semanticpen.com)
- 🐛 Report bugs on [GitHub](https://github.com/semanticpen/python-sdk/issues)
---
**Made with ❤️ by the SemanticPen team**
Raw data
{
"_id": null,
"home_page": null,
"name": "semanticpen",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "SemanticPen <contact@semanticpen.com>",
"keywords": "ai article writer, seo blog writer, ai content generator, automated article writing, ai blog generator, seo content creation, ai writing assistant, article generation api, content automation, ai copywriting, blog writing ai, seo article generator, ai content writer, automated blogging, ai text generator, content writing ai, seo blog automation, ai article creation, blog content generator, ai seo writer, semanticpen, ai, article, generation, content, writing, api, sdk, python, seo, blog, automated-writing, content-creation, ai-writer",
"author": null,
"author_email": "SemanticPen <contact@semanticpen.com>",
"download_url": "https://files.pythonhosted.org/packages/77/cc/167cd438b237085213fbd0bf49a717a44fe05c9c4e27a01d472aada39c5c/semanticpen-1.0.0.tar.gz",
"platform": null,
"description": "# SemanticPen Python SDK\n\n[](https://badge.fury.io/py/semanticpen)\n[](https://pypi.org/project/semanticpen/)\n[](https://opensource.org/licenses/MIT)\n\n**AI Article Writer & SEO Blog Generator SDK** - Professional Python library for automated content creation, AI-powered article generation, and SEO blog writing with [SemanticPen](https://www.semanticpen.com).\n\n## \ud83d\ude80 Features\n\n- **AI-Powered Article Generation**: Generate high-quality articles from keywords\n- **SEO Optimization**: Built-in SEO best practices and optimization\n- **Bulk Operations**: Generate multiple articles simultaneously\n- **Real-time Status Tracking**: Monitor article generation progress\n- **Type Safety**: Full typing support with dataclasses and type hints\n- **Error Handling**: Comprehensive error handling and retry mechanisms\n- **Async Support**: Built for high-performance applications\n- **Flexible Configuration**: Customizable settings for different use cases\n\n## \ud83d\udce6 Installation\n\n```bash\npip install semanticpen\n```\n\n## \ud83d\udd11 Quick Start\n\n### Basic Usage\n\n```python\nfrom semanticpen import SemanticPenClient\n\n# Initialize client\nclient = SemanticPenClient.create(\"your-api-key\")\n\n# Generate a single article\nresult = client.generate_article(\"Python programming best practices\")\nprint(f\"Article ID: {result['articleId']}\")\nprint(f\"Project ID: {result['projectId']}\")\nprint(f\"Message: {result['message']}\")\n\n# Check article status\nstatus = client.get_article_status(result['articleId'])\nprint(f\"Status: {status['status']}\")\nprint(f\"Complete: {status['isComplete']}\")\n```\n\n### Advanced Configuration\n\n```python\nfrom semanticpen import SemanticPenClient, SemanticPenConfig\n\n# Custom configuration\nconfig = SemanticPenConfig(\n api_key=\"your-api-key\",\n base_url=\"https://www.semanticpen.com\",\n timeout=60000, # 60 seconds\n debug=True\n)\n\nclient = SemanticPenClient.create_with_config(config)\n```\n\n## \ud83d\udcdd Core Features\n\n### 1. Article Generation\n\n#### Single Article\n```python\n# Simple generation\nresult = client.generate_article(\"AI in healthcare\")\n\n# With options\nresult = client.generate_article(\n \"Machine learning algorithms\",\n gpt_version=\"gpt-4\",\n project_name=\"AI Blog Series\",\n preset_id=\"seo-optimized\"\n)\n```\n\n#### Bulk Generation\n```python\nkeywords = [\n \"Python web development\",\n \"Django best practices\", \n \"FastAPI tutorial\"\n]\n\nresults = client.generate_articles(keywords)\nprint(f\"Successfully generated: {results.success_count}\")\nprint(f\"Failed: {results.failure_count}\")\n```\n\n### 2. Article Retrieval\n\n```python\n# Get complete article\narticle = client.get_article(\"article-id\")\nprint(f\"Title: {article.title}\")\nprint(f\"Content: {article.article_html}\")\nprint(f\"Status: {article.status}\")\n\n# Get multiple articles\narticle_ids = [\"id1\", \"id2\", \"id3\"]\nresults = client.get_articles(article_ids)\n\nfor article in results.successful:\n print(f\"Article: {article.title}\")\n```\n\n### 3. Status Monitoring\n\n```python\n# Quick completion check\nis_complete = client.is_article_complete(\"article-id\")\n\n# Detailed status\nstatus = client.get_article_status(\"article-id\")\nprint(f\"Status: {status['status']}\")\nprint(f\"Complete: {status['isComplete']}\")\nprint(f\"Has Error: {status['hasError']}\")\n```\n\n### 4. Waiting for Completion\n\n```python\nfrom semanticpen import PollingConfig\n\n# Generate and wait for completion\narticle = client.generate_and_wait(\n \"Content marketing strategies\",\n polling_config=PollingConfig(\n interval=5000, # Check every 5 seconds\n max_attempts=60 # Max 5 minutes\n )\n)\n\nprint(f\"Completed article: {article.title}\")\nprint(f\"Content length: {len(article.article_html)}\")\n```\n\n### 5. Bulk Operations with Progress Tracking\n\n```python\ndef progress_callback(completed, total, new_articles):\n print(f\"Progress: {completed}/{total} articles completed\")\n for article in new_articles:\n print(f\" \u2713 {article.title}\")\n\n# Generate multiple articles and wait\nresult = client.generate_bulk_and_wait(\n [\"Topic 1\", \"Topic 2\", \"Topic 3\"],\n on_progress=progress_callback\n)\n\nprint(f\"Successful: {len(result['successful'])}\")\nprint(f\"Failed: {len(result['failed'])}\")\nprint(f\"Total time: {result['total_time']:.2f} seconds\")\n```\n\n## \ud83c\udfd7\ufe0f Advanced Usage\n\n### Request Builder Pattern\n\n```python\n# Complex article generation with builder pattern\nbuilder = client.create_request_builder()\n\narticles = (builder\n .keyword([\"AI ethics\", \"Machine learning bias\"])\n .gpt_version(\"gpt-4\")\n .project_name(\"AI Ethics Series\")\n .preset(\"academic\")\n .parameter(\"tone\", \"professional\")\n .parameter(\"target_audience\", \"researchers\")\n .generate_and_wait())\n\nprint(f\"Generated {len(articles)} articles\")\n```\n\n### Error Handling\n\n```python\nfrom semanticpen import (\n AuthenticationError,\n ValidationError, \n RateLimitError,\n NetworkError,\n TimeoutError\n)\n\ntry:\n result = client.generate_article(\"Python tutorials\")\nexcept AuthenticationError:\n print(\"Invalid API key\")\nexcept ValidationError as e:\n print(f\"Invalid input: {e}\")\nexcept RateLimitError as e:\n print(f\"Rate limit exceeded. Retry after: {e.retry_after}s\")\nexcept NetworkError:\n print(\"Network connection failed\")\nexcept TimeoutError:\n print(\"Request timed out\")\n```\n\n### Custom Polling Configuration\n\n```python\nfrom semanticpen import PollingConfig\n\n# Custom polling behavior\ncustom_polling = PollingConfig(\n interval=3000, # Poll every 3 seconds\n max_attempts=100, # Try for up to 100 times\n backoff_multiplier=1.2 # Increase interval by 20% each time\n)\n\narticle = client.wait_for_article(\n \"article-id\",\n polling_config=custom_polling\n)\n```\n\n## \ud83d\udd27 Configuration Options\n\n### SemanticPenConfig\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `api_key` | `str` | Required | Your SemanticPen API key |\n| `base_url` | `str` | `\"https://www.semanticpen.com\"` | API base URL |\n| `timeout` | `int` | `30000` | Request timeout in milliseconds |\n| `debug` | `bool` | `False` | Enable debug logging |\n\n### PollingConfig\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `interval` | `int` | `5000` | Polling interval in milliseconds |\n| `max_attempts` | `int` | `60` | Maximum polling attempts |\n| `backoff_multiplier` | `float` | `1.0` | Exponential backoff multiplier |\n\n## \ud83d\udcca Response Types\n\n### Article\n```python\n@dataclass\nclass Article:\n id: str\n organization_id: str\n user_id: str\n project_id: str\n target_keyword: str\n status: ArticleStatusEnum\n created_at: str\n updated_at: str\n article_html: Optional[str] = None\n content: Optional[str] = None\n title: Optional[str] = None\n metadata: Optional[Dict[str, Any]] = None\n completed_at: Optional[str] = None\n error_message: Optional[str] = None\n```\n\n### BulkOperationResult\n```python\n@dataclass\nclass BulkOperationResult:\n successful: List[Any]\n failed: List[Dict[str, Any]]\n total: int\n success_count: int\n failure_count: int\n```\n\n## \ud83e\uddea Testing\n\n```python\n# Test API connection\nif client.test_connection():\n print(\"\u2713 Connected to SemanticPen API\")\nelse:\n print(\"\u2717 Connection failed\")\n\n# Validate keywords\nvalidation = SemanticPenClient.validate_keywords([\n \"Valid keyword\",\n \"\", # Invalid\n \"Another valid keyword\"\n])\n\nif validation[\"valid\"]:\n print(\"All keywords are valid\")\nelse:\n print(f\"Validation errors: {validation['errors']}\")\n```\n\n## \ud83d\udcda API Reference\n\n### SemanticPenClient Methods\n\n| Method | Description |\n|--------|-------------|\n| `create(api_key, **options)` | Create client with API key |\n| `test_connection()` | Test API connectivity |\n| `generate_article(keyword, **options)` | Generate single article |\n| `generate_articles(keywords, **options)` | Generate multiple articles |\n| `get_article(article_id)` | Retrieve article by ID |\n| `get_articles(article_ids)` | Retrieve multiple articles |\n| `is_article_complete(article_id)` | Check if article is complete |\n| `get_article_status(article_id)` | Get article status |\n| `wait_for_article(article_id, **options)` | Wait for article completion |\n| `generate_and_wait(keyword, **options)` | Generate and wait workflow |\n\n## \ud83c\udf1f Examples\n\nSee the [`examples/`](./examples) directory for complete examples:\n\n- [`basic_usage.py`](./examples/basic_usage.py) - Simple article generation\n- [`bulk_generation.py`](./examples/bulk_generation.py) - Multiple article generation\n- [`async_monitoring.py`](./examples/async_monitoring.py) - Real-time status monitoring\n- [`error_handling.py`](./examples/error_handling.py) - Comprehensive error handling\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Links\n\n- **Website**: [https://www.semanticpen.com](https://www.semanticpen.com)\n- **API Documentation**: [https://www.semanticpen.com/api-documentation](https://www.semanticpen.com/api-documentation)\n- **Python SDK Documentation**: [https://www.semanticpen.com/api-documentation](https://www.semanticpen.com/api-documentation)\n- **Support**: [contact@semanticpen.com](mailto:contact@semanticpen.com)\n- **Issues**: [GitHub Issues](https://github.com/semanticpen/python-sdk/issues)\n\n## \ud83d\udca1 Need Help?\n\n- \ud83d\udcd6 Check our [documentation](https://www.semanticpen.com/api-documentation)\n- \ud83d\udcac Join our [community forum](https://community.semanticpen.com) \n- \ud83d\udce7 Email us at [support@semanticpen.com](mailto:support@semanticpen.com)\n- \ud83d\udc1b Report bugs on [GitHub](https://github.com/semanticpen/python-sdk/issues)\n\n---\n\n**Made with \u2764\ufe0f by the SemanticPen team**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI Article Writer & SEO Blog Generator SDK - Professional Python library for automated content creation, AI-powered article generation, and SEO blog writing with SemanticPen",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/semanticpen/python-sdk/issues",
"Changelog": "https://github.com/semanticpen/python-sdk/blob/main/CHANGELOG.md",
"Documentation": "https://www.semanticpen.com/api-documentation",
"Funding": "https://www.semanticpen.com/pricing",
"Homepage": "https://www.semanticpen.com",
"Repository": "https://github.com/semanticpen/python-sdk.git"
},
"split_keywords": [
"ai article writer",
" seo blog writer",
" ai content generator",
" automated article writing",
" ai blog generator",
" seo content creation",
" ai writing assistant",
" article generation api",
" content automation",
" ai copywriting",
" blog writing ai",
" seo article generator",
" ai content writer",
" automated blogging",
" ai text generator",
" content writing ai",
" seo blog automation",
" ai article creation",
" blog content generator",
" ai seo writer",
" semanticpen",
" ai",
" article",
" generation",
" content",
" writing",
" api",
" sdk",
" python",
" seo",
" blog",
" automated-writing",
" content-creation",
" ai-writer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "784b19af6a68c626561c3583555aff6afb34579a1a19cdbd2e7e68d0f49d34e2",
"md5": "cbcaaa0f3f2f11befbdfa457cd2efc7e",
"sha256": "a8ced2467b4dfdaaae6b3793fb06676b8965ff7eef9b0ff53e04f9b3384700c6"
},
"downloads": -1,
"filename": "semanticpen-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cbcaaa0f3f2f11befbdfa457cd2efc7e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23038,
"upload_time": "2025-07-19T09:40:49",
"upload_time_iso_8601": "2025-07-19T09:40:49.717676Z",
"url": "https://files.pythonhosted.org/packages/78/4b/19af6a68c626561c3583555aff6afb34579a1a19cdbd2e7e68d0f49d34e2/semanticpen-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "77cc167cd438b237085213fbd0bf49a717a44fe05c9c4e27a01d472aada39c5c",
"md5": "5bd2d10594e725616c839e17c670cd6c",
"sha256": "b8446b2b9a2c6dd98913bd4274254b0f0abfb4769c8bbcf823f64097bf696bee"
},
"downloads": -1,
"filename": "semanticpen-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "5bd2d10594e725616c839e17c670cd6c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 33262,
"upload_time": "2025-07-19T09:40:51",
"upload_time_iso_8601": "2025-07-19T09:40:51.511044Z",
"url": "https://files.pythonhosted.org/packages/77/cc/167cd438b237085213fbd0bf49a717a44fe05c9c4e27a01d472aada39c5c/semanticpen-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 09:40:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "semanticpen",
"github_project": "python-sdk",
"github_not_found": true,
"lcname": "semanticpen"
}
JSON
