PyPI - devrev-Python-SDK - Versions diffs - 2.7.0__tar.gz → 2.8.0__tar.gz - Mend

devrev-Python-SDK 2.7.0tar.gz → 2.8.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (362) hide show

devrev_python_sdk-2.8.0/.github/ISSUE_TEMPLATE/article-artifact-simplification.md ADDED Viewed

@@ -0,0 +1,582 @@
+# Simplify DevRev Article & Artifact Management in SDK and MCP Tools
+## Problem Statement
+The DevRev API separates articles into two entities that must be managed separately:
+- **Articles** – contain metadata and a "description" field (which is NOT the article's main content)
+- **Artifacts** – store the actual body/content of an article
+Currently, the SDK methods are thin wrappers that directly mirror these individual API endpoints, forcing consumers to understand and manage both entities separately. This creates unnecessary complexity for common operations like creating, reading, updating, and deleting articles with their content.
+### Example of Current Complexity
+To create an article with content today:
+```python
+# 1. Prepare artifact
+prepare_req = ArtifactPrepareRequest(
+    file_name="article.html",
+    file_type="text/html",
+    configuration_set="article_media"
+)
+prepare_resp = client.artifacts.prepare(prepare_req)
+# 2. Upload content to S3
+import httpx
+form_data = {item.key: item.value for item in prepare_resp.form_data}
+httpx.post(prepare_resp.url, data=form_data, files={"file": content})
+# 3. Create article with artifact reference
+article_req = ArticlesCreateRequest(
+    title="My Article",
+    owned_by=["DEVU-123"],
+    resource={"content_artifact": prepare_resp.id}
+)
+article = client.articles.create(article_req)
+```
+This should be as simple as:
+```python
+article = client.articles.create_with_content(
+    title="My Article",
+    content="<html>...</html>",
+    owned_by=["DEVU-123"]
+)
+```
+## Goal
+Refactor the SDK and the related MCP tools to provide a **unified, higher-level abstraction** for article management that hides the article/artifact separation from the consumer, while preserving access to all underlying functionality.
+## User Impact
+**Who Benefits:**
+- SDK users who need to create/manage articles with content
+- MCP tool users (AI agents) working with articles
+- New developers integrating DevRev article functionality
+- Technical writers managing documentation
+**Time Savings:**
+- Current: 15-20 lines of code + error handling for article creation
+- New: 3-5 lines of code with automatic error handling
+- Estimated 70% reduction in integration time
+**Pain Points Addressed:**
+- No need to understand artifact lifecycle
+- No manual S3 upload handling
+- No artifact ID management
+- Automatic rollback on failures
+- Clear separation of content vs metadata
+## Investigation Findings
+### API Architecture Discovery
+Based on OpenAPI spec analysis:
+**Articles API** (`/articles.*`)
+- Manages article metadata (title, status, description)
+- `resource` field contains artifact references:
+  - `content_artifact` - ID of artifact containing article body
+  - `attachments` - IDs of attachment artifacts
+  - `artifacts` - (deprecated) legacy references
+- `description` field is SHORT metadata, NOT article content
+**Artifacts API** (`/artifacts.*`)
+- Manages file storage (S3-style)
+- `artifacts.prepare` - creates artifact + upload URL
+- `artifacts.get` - retrieves metadata
+- `artifacts.list` - lists artifacts for parent
+- `artifacts.locate` - gets download URL
+- `artifact-configuration-set` enum includes `article_media` for article content
+**Complete Workflow:**
+1. `artifacts.prepare` with `configuration_set: article_media`
+2. Upload content to returned S3 URL
+3. `articles.create` with `resource.content_artifact` = artifact ID
+4. To update: `artifacts.versions.prepare` for new version
+5. To read: `artifacts.locate` → fetch from URL
+### Current State
+**SDK:**
+- ✅ ArticlesService with basic CRUD
+- ❌ No ArtifactsService
+- ❌ No unified methods
+**MCP Tools:**
+- ✅ Basic article operations
+- ❌ Misleading `description` parameter (users think it's content)
+- ❌ No artifact operations
+## Proposed Solution
+### 1. Artifacts Service Foundation
+Create complete artifact management:
+```python
+class ArtifactsService(BaseService):
+    def prepare(self, request: ArtifactPrepareRequest) -> ArtifactPrepareResponse
+    def upload(self, prepare_response: ArtifactPrepareResponse, content: bytes | str) -> str
+    def get(self, request: ArtifactGetRequest) -> Artifact
+    def locate(self, request: ArtifactLocateRequest) -> str
+    def download(self, artifact_id: str, version: str | None = None) -> bytes
+    def list_for_parent(self, parent_id: str) -> list[Artifact]
+    def prepare_version(self, request: ArtifactVersionsPrepareRequest) -> ArtifactVersionsPrepareResponse
+    def delete_version(self, request: ArtifactVersionsDeleteRequest) -> None
+```
+### 2. Unified Article Methods
+Add high-level methods to ArticlesService:
+```python
+class ArticlesService(BaseService):
+    # Existing methods remain unchanged
+    def create(self, request: ArticlesCreateRequest) -> Article
+    def get(self, request: ArticlesGetRequest) -> Article
+    # ...
+    # NEW unified methods
+    def create_with_content(
+        self,
+        title: str,
+        content: str,
+        *,
+        owned_by: list[str],
+        description: str | None = None,
+        status: ArticleStatus | None = None,
+        content_format: str = "text/plain",
+        **kwargs
+    ) -> Article:
+        """Create article with content in a single operation."""
+    def get_with_content(self, id: str) -> ArticleWithContent:
+        """Get article with its content in a single call."""
+    def update_content(
+        self,
+        id: str,
+        content: str,
+        content_format: str | None = None
+    ) -> Article:
+        """Update article content by creating new artifact version."""
+    def update_with_content(
+        self,
+        id: str,
+        *,
+        title: str | None = None,
+        content: str | None = None,
+        description: str | None = None,
+        status: ArticleStatus | None = None,
+        **kwargs
+    ) -> Article:
+        """Update article metadata and/or content."""
+```
+### 3. New Models
+```python
+class ArticleWithContent(DevRevResponseModel):
+    """Article with its content loaded."""
+    article: Article
+    content: str
+    content_format: str
+    content_version: str | None
+```
+### 4. MCP Tool Updates
+Update tools to use unified methods:
+```python
+@mcp.tool()
+async def devrev_articles_create(
+    ctx: Context,
+    title: str,
+    content: str,  # Changed from 'description' to 'content'
+    owned_by: list[str],
+    description: str | None = None,  # Optional metadata
+    status: str | None = None,
+    content_format: str = "text/html"
+) -> dict[str, Any]:
+    """Create a new article with content.
+    Args:
+        title: Article title
+        content: The article body content (HTML, markdown, or plain text)
+        owned_by: List of dev user IDs
+        description: Optional short metadata description
+        status: Optional article status (draft, published, archived)
+        content_format: Content MIME type
+    """
+```
+## Error Handling Strategy
+### Atomic Operations
+All unified methods implement atomic operations with automatic rollback:
+1. **create_with_content** - If artifact upload fails, no article is created
+2. **update_content** - If new version upload fails, article reference unchanged
+3. **Cleanup** - Failed uploads automatically delete orphaned artifacts
+### Error Scenarios
+| Scenario | Behavior | User Experience |
+|----------|----------|-----------------|
+| Artifact prepare fails | Raise DevRevError before upload | Clear error message |
+| Upload to S3 fails | Delete artifact, raise error | No orphaned artifacts |
+| Article create fails | Delete uploaded artifact | Complete rollback |
+| Network timeout | Retry with exponential backoff | Automatic recovery |
+| Invalid content format | Validate before upload | Fast failure |
+### Retry Strategy
+- Network errors: 3 retries with exponential backoff
+- Rate limits: Automatic retry with proper delays
+- Server errors (5xx): Retry with backoff
+- Client errors (4xx): No retry, immediate failure
+## Performance Considerations
+### Optimization Strategies
+1. **Lazy Loading**
+   - `get()` returns metadata only (fast)
+   - `get_with_content()` fetches content only when needed
+   - Explicit opt-in for content loading
+2. **Caching**
+   - Cache artifact download URLs (valid for 15 minutes)
+   - Optional local content caching
+   - Respect HTTP cache headers from S3
+3. **Bulk Operations** (Future Enhancement)
+   ```python
+   # Efficient batch creation
+   articles = client.articles.bulk_create_with_content([
+       {"title": "Article 1", "content": "..."},
+       {"title": "Article 2", "content": "..."},
+   ])
+   ```
+4. **Streaming Support** (Future Enhancement)
+   - Large content streaming for articles >10MB
+   - Progress callbacks for uploads
+   - Chunked uploads for reliability
+### Benchmarks (Target)
+- `create_with_content()`: <2s for typical article (50KB)
+- `get_with_content()`: <1s for cached content
+- `update_content()`: <1.5s for version update
+- Overhead vs manual: <200ms
+## Implementation Plan
+### Phase 1: Artifact Service Foundation ✅
+- [x] Create artifact models (`src/devrev/models/artifacts.py`)
+- [x] Create `ArtifactsService` class (`src/devrev/services/artifacts.py`)
+- [x] Implement basic artifact operations (prepare, upload, get, locate, download)
+- [x] Update client to expose `client.artifacts`
+- [x] Add `ArticleWithContent` model
+- [ ] Add tests for artifact service
+### Phase 2: Unified Article Methods ✅
+**Architectural Decision**: Option 2 (Store client reference in service) ✅
+**Implementation Complete:**
+```python
+class BaseService:
+    def __init__(self, http_client, parent_client=None):
+        self._http = http_client
+        self._parent_client = parent_client
+class ArticlesService(BaseService):
+    def create_with_content(...):
+        # Accesses self._parent_client.artifacts
+```
+**Tasks:**
+- [x] Decide on architectural approach (Option 2 selected)
+- [x] Modify BaseService to accept parent_client parameter
+- [x] Update client initialization to pass parent_client=self
+- [x] Implement `create_with_content` in ArticlesService (sync + async)
+- [x] Implement `get_with_content` in ArticlesService (sync + async)
+- [x] Implement `update_content` in ArticlesService (sync + async)
+- [x] Implement `update_with_content` in ArticlesService (sync + async)
+- [x] Add `resource` field to Article model
+- [ ] Add tests for unified methods
+### Phase 3: MCP Tool Updates ✅
+- [x] Update `devrev_articles_create` to use `create_with_content`
+  - Changed `description` param to `content` (article body)
+  - Added `description` as optional metadata
+  - Added `content_format` parameter
+- [x] Update `devrev_articles_get` to support `include_content` parameter
+  - `include_content=False` → metadata only
+  - `include_content=True` → full ArticleWithContent
+- [x] Update `devrev_articles_update` to support content updates
+  - Added `content` parameter for body updates
+  - Uses `update_with_content()` method
+- [x] Update tool docstrings to clarify content vs description
+- [ ] Add integration tests for MCP tools
+### Phase 4: Documentation ✅
+- [x] Update SDK documentation with unified examples
+  - [x] docs/api/services/articles.md - Added comprehensive examples
+  - [x] docs/api/services/index.md - Added unified article management section
+  - [x] README.md - Updated article examples with unified methods
+  - [x] docs/mcp/tools-reference.md - Updated article tools descriptions
+  - [x] docs/changelog.md - Added unreleased section documenting changes
+- [x] Add migration guide for existing users (included in issue template)
+- [x] Update MCP tool descriptions
+- [x] Add examples showing both high-level and low-level usage
+## Migration Guide Preview
+### Before (Current SDK)
+```python
+from devrev import DevRevClient
+from devrev.models import ArticlesCreateRequest, ArtifactPrepareRequest
+import httpx
+client = DevRevClient(api_token="...")
+# 1. Prepare artifact
+prepare_req = ArtifactPrepareRequest(
+    file_name="guide.html",
+    file_type="text/html",
+    configuration_set="article_media"
+)
+prepare_resp = client.artifacts.prepare(prepare_req)
+# 2. Upload to S3
+form_data = {item.key: item.value for item in prepare_resp.form_data}
+httpx.post(prepare_resp.url, data=form_data, files={"file": content})
+# 3. Create article
+article_req = ArticlesCreateRequest(
+    title="User Guide",
+    owned_by=["DEVU-123"],
+    resource={"content_artifact": prepare_resp.id}
+)
+article = client.articles.create(article_req)
+```
+### After (Unified SDK)
+```python
+from devrev import DevRevClient
+client = DevRevClient(api_token="...")
+# Single unified call
+article = client.articles.create_with_content(
+    title="User Guide",
+    content="<html>...</html>",
+    owned_by=["DEVU-123"],
+    content_format="text/html"
+)
+```
+### MCP Tool Changes
+**Before:**
+```python
+# Misleading - 'description' sounds like metadata but was used for content
+devrev_articles_create(
+    title="API Guide",
+    description="<html>...</html>",  # Confusing parameter name
+    owned_by=["DEVU-123"]
+)
+```
+**After:**
+```python
+# Clear separation of content vs metadata
+devrev_articles_create(
+    title="API Guide",
+    content="<html>...</html>",  # Clear: this is the article body
+    description="A guide for API usage",  # Clear: this is metadata
+    owned_by=["DEVU-123"]
+)
+```
+## API Compatibility Matrix
+| Feature | SDK Version | API Version | Breaking Change |
+|---------|-------------|-------------|-----------------|
+| Existing `articles.create()` | All | Public/Beta | ✅ No change |
+| Existing `articles.get()` | All | Public/Beta | ✅ No change |
+| `ArtifactsService` | 2.7.0+ | Public/Beta | ➕ New |
+| `create_with_content()` | 2.8.0+ | Public/Beta | ➕ New |
+| `get_with_content()` | 2.8.0+ | Public/Beta | ➕ New |
+| `update_content()` | 2.8.0+ | Public/Beta | ➕ New |
+| MCP `content` parameter | 2.8.0+ | Public/Beta | ⚠️ Signature change |
+**Upgrade Path:**
+- SDK 2.6.x → 2.7.x: Add artifacts service (no breaking changes)
+- SDK 2.7.x → 2.8.x: Add unified methods (no breaking changes)
+- MCP tools 2.8.x: Update to use `content` parameter (may affect existing AI workflows)
+## Security Considerations
+### Input Validation
+- **Content Size Limits**: Enforce max article size (configurable, default 10MB)
+- **Content Type Validation**: Whitelist allowed MIME types
+- **HTML Sanitization**: Optional HTML sanitization for user-generated content
+- **Injection Prevention**: Validate artifact IDs match expected format
+### Access Control
+- Respect existing DevRev RBAC for articles and artifacts
+- Validate ownership before allowing content updates
+- Audit logging for all content operations
+### Data Protection
+- Content encrypted in transit (HTTPS to S3)
+- S3 URLs are signed and time-limited (15-minute expiry)
+- No credentials in error messages or logs
+- Sensitive content redaction in debug logs
+### Artifact Cleanup
+- Orphaned artifact detection and cleanup
+- Automatic deletion of artifacts when parent article deleted
+- Version retention policies (keep last N versions)
+## Testing Strategy
+### Unit Tests
+- [ ] Each artifact method (prepare, upload, get, locate, download)
+- [ ] Each unified article method (create_with_content, get_with_content, update_content)
+- [ ] Model validation (all request/response models)
+- [ ] Error handling for each failure scenario
+- [ ] Async versions of all methods
+### Integration Tests
+- [ ] Full article+artifact lifecycle (create → read → update → delete)
+- [ ] Multi-version artifact updates
+- [ ] Large content handling (>1MB)
+- [ ] Network failure recovery
+- [ ] Concurrent operations (race conditions)
+### Performance Tests
+- [ ] Benchmark create_with_content vs manual workflow
+- [ ] Large content upload performance (5MB, 10MB)
+- [ ] Bulk operation performance
+- [ ] Cache effectiveness
+### Backward Compatibility Tests
+- [ ] All existing SDK tests pass without modification
+- [ ] Existing code examples still work
+- [ ] API contract unchanged for existing methods
+- [ ] MCP tools with old signatures still function (deprecation warnings)
+### MCP Integration Tests
+- [ ] AI agent workflows with new tools
+- [ ] Content vs description parameter handling
+- [ ] Error messages clear for AI interpretation
+- [ ] Tool schema validation
+## Breaking Changes Assessment
+**No breaking changes** - all existing methods remain unchanged:
+- ✅ Existing `articles.create(request)` still works
+- ✅ Existing `articles.get(request)` still works
+- ✅ New methods are additions, not replacements
+- ✅ MCP tools will have enhanced signatures but maintain compatibility where possible
+## Success Criteria
+- [ ] SDK provides unified `create_with_content`, `get_with_content`, `update_content` methods
+- [ ] MCP tools use `content` parameter for article body (not `description`)
+- [ ] All existing tests pass
+- [ ] New tests cover unified methods and artifact operations
+- [ ] Documentation clearly explains content vs description
+- [ ] Migration guide helps users adopt new methods
+- [ ] No breaking changes to existing API
+## Related Files
+- `src/devrev/models/artifacts.py` - Artifact models ✅
+- `src/devrev/services/artifacts.py` - Artifacts service ✅
+- `src/devrev/services/articles.py` - Articles service (needs unified methods)
+- `src/devrev/models/articles.py` - Article models (added ArticleWithContent ✅)
+- `src/devrev/client.py` - Client integration ✅
+- `src/devrev_mcp/tools/articles.py` - MCP tools (needs updates)
+- `tests/unit/test_artifacts.py` - Artifact tests (to create)
+- `tests/unit/test_articles_unified.py` - Unified method tests (to create)
+- `docs/api/services/articles.md` - Documentation (needs updates)
+## Rollout Strategy
+### Week 1: Foundation (Phase 1)
+- ✅ Create and test `ArtifactsService`
+- ✅ Add `ArticleWithContent` model
+- ✅ Integration with client
+- [ ] Complete unit tests for artifacts
+- Release as SDK 2.7.0 (non-breaking, adds artifact support)
+### Week 2: Unified Methods (Phase 2)
+- [ ] Implement `create_with_content()`
+- [ ] Implement `get_with_content()`
+- [ ] Implement `update_content()`
+- [ ] Complete unit and integration tests
+- Release as SDK 2.8.0-beta1 (non-breaking, adds unified methods)
+### Week 3: MCP Tools + Documentation (Phases 3-4)
+- [ ] Update MCP tools with `content` parameter
+- [ ] Add deprecation warnings for old usage
+- [ ] Write migration guide
+- [ ] Update all documentation
+- Release as SDK 2.8.0-beta2
+### Week 4: Final Testing + Release
+- [ ] Community beta testing
+- [ ] Performance benchmarking
+- [ ] Address feedback
+- [ ] Final documentation review
+- Release as SDK 2.8.0 (stable)
+## FAQ
+**Q: Will this break my existing code?**
+A: No. All existing methods remain unchanged. New unified methods are additions.
+**Q: Can I still use the low-level artifact methods?**
+A: Yes. Both `client.artifacts` and unified methods will be available.
+**Q: What happens if I call `create_with_content()` and it fails?**
+A: Automatic rollback ensures no orphaned artifacts. You'll get a clear error message.
+**Q: How do I migrate from `description` to `content` in MCP tools?**
+A: The migration guide provides before/after examples. Old usage will show deprecation warnings.
+**Q: What content formats are supported?**
+A: Any format - text/plain, text/html, text/markdown. Specify via `content_format` parameter.
+**Q: Is there a size limit for article content?**
+A: Default limit is 10MB. Configurable via SDK settings.
+**Q: How do I handle large articles (>10MB)?**
+A: Use the low-level `artifacts.prepare()` + `upload()` for more control. Streaming support coming in future release.
+**Q: Can I version article content?**
+A: Yes. The `update_content()` method creates a new artifact version automatically.
+**Q: What if I need to attach multiple files to an article?**
+A: Use the `resource.attachments` field with multiple artifact IDs. Unified helper method for attachments planned for future release.
+**Q: How does this affect the DevRev MCP server?**
+A: MCP tools will use the new unified methods, making article operations simpler for AI agents.
+## Progress Tracking
+**Overall: 90% Complete** ⬆️
+✅ Phase 1: Artifact Service Foundation (100%)
+✅ Phase 2: Unified Article Methods (100%) 🎉
+✅ Phase 3: MCP Tool Updates (100%) 🎉
+✅ Phase 4: Documentation (100%) 🎉
+⏳ Phase 5: Testing (0%)
+**Documentation Complete!** All SDK docs, MCP docs, README, and changelog have been updated with unified method examples.

{devrev_python_sdk-2.7.0 → devrev_python_sdk-2.8.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devrev-Python-SDK
-Version: 2.7.0
+Version: 2.8.0
 Summary: A modern, type-safe Python SDK for the DevRev API
 Project-URL: Homepage, https://github.com/mgmonteleone/py-dev-rev
 Project-URL: Documentation, https://github.com/mgmonteleone/py-dev-rev
@@ -505,24 +505,40 @@ export_result = client.works.export(
 ### Articles and Knowledge Base
 ```python
-# Create an article
-article = client.articles.create(
+from devrev.models.articles import ArticleStatus
+# Create an article with content (recommended - automatic artifact handling)
+article = client.articles.create_with_content(
     title="Getting Started Guide",
-    applies_to_parts=["don:core:..."],
-    authored_by="don:identity:...",
-    description="# Welcome\n\nThis guide will help you get started..."
+    content="<h1>Welcome</h1><p>This guide will help you get started...</p>",
+    owned_by=["don:identity:dvrv-us-1:devo/1:devu/1"],
+    description="Quick start guide for new users",  # Optional metadata
+    status=ArticleStatus.PUBLISHED,
 )
-# List published articles
-published = client.articles.list(
-    status=["published"]
+# Get article with content
+article_with_content = client.articles.get_with_content(article.id)
+print(f"Title: {article_with_content.article.title}")
+print(f"Content: {article_with_content.content[:100]}...")
+# Update article content
+client.articles.update_content(
+    id=article.id,
+    content="<h1>Updated Welcome</h1><p>Updated guide...</p>",
 )
-# Update article description
-client.articles.update(
+# Update both metadata and content
+client.articles.update_with_content(
     id=article.id,
-    description="# Updated Description\n\n..."
+    title="Updated Getting Started Guide",
+    content="<h1>New Content</h1>",
+    status=ArticleStatus.ARCHIVED,
 )
+# List published articles (metadata only)
+published = client.articles.list(limit=20)
+for article in published:
+    print(f"{article.title} - {article.status}")
 ```
 ### Webhooks

{devrev_python_sdk-2.7.0 → devrev_python_sdk-2.8.0}/README.md RENAMED Viewed

@@ -433,24 +433,40 @@ export_result = client.works.export(
 ### Articles and Knowledge Base
 ```python
-# Create an article
-article = client.articles.create(
+from devrev.models.articles import ArticleStatus
+# Create an article with content (recommended - automatic artifact handling)
+article = client.articles.create_with_content(
     title="Getting Started Guide",
-    applies_to_parts=["don:core:..."],
-    authored_by="don:identity:...",
-    description="# Welcome\n\nThis guide will help you get started..."
+    content="<h1>Welcome</h1><p>This guide will help you get started...</p>",
+    owned_by=["don:identity:dvrv-us-1:devo/1:devu/1"],
+    description="Quick start guide for new users",  # Optional metadata
+    status=ArticleStatus.PUBLISHED,
 )
-# List published articles
-published = client.articles.list(
-    status=["published"]
+# Get article with content
+article_with_content = client.articles.get_with_content(article.id)
+print(f"Title: {article_with_content.article.title}")
+print(f"Content: {article_with_content.content[:100]}...")
+# Update article content
+client.articles.update_content(
+    id=article.id,
+    content="<h1>Updated Welcome</h1><p>Updated guide...</p>",
 )
-# Update article description
-client.articles.update(
+# Update both metadata and content
+client.articles.update_with_content(
     id=article.id,
-    description="# Updated Description\n\n..."
+    title="Updated Getting Started Guide",
+    content="<h1>New Content</h1>",
+    status=ArticleStatus.ARCHIVED,
 )
+# List published articles (metadata only)
+published = client.articles.list(limit=20)
+for article in published:
+    print(f"{article.title} - {article.status}")
 ```
 ### Webhooks

devrev-Python-SDK 2.7.0__tar.gz → 2.8.0__tar.gz

devrev-Python-SDK 2.7.0tar.gz → 2.8.0tar.gz