327 lines
No EOL
12 KiB
Markdown
327 lines
No EOL
12 KiB
Markdown
# Release Notes
|
|
|
|
## v0.0.1b2 - Major Enhancements & Restructuring (2025-07-22)
|
|
|
|
🚀 **A comprehensive update focusing on developer experience, code organization, and expanded examples!**
|
|
|
|
This release brings significant improvements to the SDK structure, comprehensive examples for all features, and enhanced developer experience.
|
|
|
|
### 🎯 **Major Features Examples**
|
|
|
|
#### 📹 **Comprehensive Video Generation Examples**
|
|
- **Complete Model Coverage**: Added examples for all supported video generation models:
|
|
- `cogvideox-3`: Text-to-video, image-to-video, start-end frame video
|
|
- `cogvideox-2`: Enhanced text-to-video generation
|
|
- `viduq1-text`, `viduq1-image`, `viduq1-start-end`: VidU Q1 series models
|
|
- `vidu2-image`, `vidu2-start-end`, `vidu2-reference`: VidU 2 series models
|
|
- **Advanced Features**: Support for 4K resolution, 60fps, audio generation, and custom quality settings
|
|
- **Async Task Management**: Comprehensive polling and timeout handling for video generation tasks
|
|
|
|
#### 🤖 **Agent Invocation System Examples**
|
|
- **General Translation Agent**: Multi-language translation with streaming support
|
|
- Supports 10 languages: English, Chinese, Japanese, Korean, French, German, Spanish, Russian, Arabic, Portuguese
|
|
- Real-time streaming translation responses
|
|
- **Special Effects Video Agent**: Advanced video creation with template support
|
|
- Async task submission and result polling
|
|
- Template-based video generation (e.g., "french_kiss" template)
|
|
- Image input support for video effects
|
|
|
|
#### 🧠 **GLM-4 Model Integration Examples**
|
|
- **Synchronous Calls**: Direct model invocation with web search tool integration
|
|
- **Streaming Responses**: Real-time text generation with SSE support
|
|
- **Asynchronous Operations**: Task-based async processing with result polling
|
|
- **Tool Integration**: Built-in web search capabilities for enhanced responses
|
|
|
|
#### 🔍 **Web Search Examples**
|
|
- **Advanced Search Filters**: Domain filtering, recency filtering, content size control
|
|
- **Multiple Search Engines**: Support for different search engines including "search_pro"
|
|
- **Configurable Results**: Customizable result count (1-50) and content detail level
|
|
- **GLM-4 Integration**: Seamless integration with chat models for search-enhanced responses
|
|
|
|
### 🏗️ **Architecture & Code Organization**
|
|
|
|
#### 📁 **Module Structure Refactoring**
|
|
- **API Resources Reorganization**:
|
|
```
|
|
src/zai/api_resource/
|
|
├── embeddings/
|
|
│ ├── __init__.py
|
|
│ └── embeddings.py
|
|
├── files/
|
|
│ ├── __init__.py
|
|
│ └── files.py
|
|
├── images/
|
|
│ ├── __init__.py
|
|
│ └── images.py
|
|
└── batch/
|
|
├── __init__.py
|
|
└── batches.py
|
|
```
|
|
|
|
- **Type Definitions Reorganization**:
|
|
```
|
|
src/zai/types/
|
|
├── batch/
|
|
│ ├── __init__.py
|
|
│ ├── batch.py
|
|
│ ├── batch_create_params.py
|
|
│ ├── batch_error.py
|
|
│ ├── batch_list_params.py
|
|
│ └── batch_request_counts.py
|
|
├── image/
|
|
│ ├── __init__.py
|
|
│ └── image.py
|
|
├── embeddings/
|
|
│ ├── __init__.py
|
|
│ └── embeddings.py
|
|
└── [other organized modules...]
|
|
```
|
|
|
|
#### 🔗 **Import System Overhaul**
|
|
- **Absolute Imports**: Converted all relative imports (`from ..core`) to absolute imports (`from zai.core`)
|
|
- **Centralized Exports**: Moved all `__all__` definitions from individual modules to `__init__.py` files
|
|
- **Backward Compatibility**: Maintained full compatibility with existing import patterns
|
|
- **Clean Dependencies**: Eliminated circular imports and improved module loading
|
|
|
|
### 🛠️ **Developer Experience Improvements**
|
|
|
|
#### ⚙️ **Environment Configuration**
|
|
- **Enhanced .env Support**: Robust environment variable loading with `python-dotenv`
|
|
- **Fallback Mechanisms**: Graceful fallback to system environment variables
|
|
- **API Key Validation**: Comprehensive error handling for missing or invalid API keys
|
|
- **Setup Guidance**: Clear instructions for environment configuration
|
|
|
|
#### 🌍 **Internationalization**
|
|
- **Complete English Translation**: All Chinese content translated to English
|
|
- Code comments and documentation
|
|
- Print statements and user messages
|
|
- Error messages and status updates
|
|
- Example code and variable names
|
|
- **Consistent Terminology**: Standardized technical terms across all examples
|
|
|
|
### 📚 **Comprehensive Example Suite**
|
|
|
|
#### 📖 **New Example Files**
|
|
- **`examples/video_models_examples.py`**: Complete guide for all video generation models
|
|
- **`examples/agent_examples.py`**: Agent invocation patterns and best practices
|
|
- **`examples/glm4_example.py`**: GLM-4 model usage in all modes (sync, async, streaming)
|
|
- **`examples/web_search_example.py`**: Web search integration and configuration
|
|
- **`examples/video_generator.py`**: Enhanced async video generation (updated)
|
|
|
|
#### 🔧 **Enhanced Existing Examples**
|
|
- **`examples/basic_usage.py`**: Maintained comprehensive basic SDK usage
|
|
- **Error Handling**: Added proper exception handling across all examples
|
|
- **Type Hints**: Enhanced type annotations for better IDE support
|
|
- **Documentation**: Improved inline documentation and usage explanations
|
|
|
|
### 🐛 **Bug Fixes & Stability**
|
|
|
|
#### 🔧 **Import Resolution**
|
|
- Fixed `ModuleNotFoundError` issues after module restructuring
|
|
- Corrected import paths in `src/zai/_client.py` for batch operations
|
|
- Resolved circular dependency issues in type definitions
|
|
- Ensured backward compatibility for existing test imports
|
|
|
|
#### 🔑 **API Key Management**
|
|
- Fixed API key loading from `.env` files
|
|
- Enhanced error messages for authentication issues
|
|
- Improved error handling for missing environment variables
|
|
|
|
#### ⏱️ **Async Operations**
|
|
- Enhanced timeout and polling mechanisms for video generation
|
|
- Improved error handling in async task management
|
|
- Better exception handling for network and API errors
|
|
|
|
### 📋 **Technical Improvements**
|
|
|
|
#### 🏃♂️ **Performance Optimizations**
|
|
- Optimized module loading with improved import structure
|
|
- Reduced memory footprint through better resource management
|
|
- Enhanced async operation handling in examples
|
|
|
|
#### 🛡️ **Code Quality**
|
|
- Consistent error handling patterns across all modules
|
|
- Enhanced type safety with comprehensive type hints
|
|
- Improved code documentation and comments
|
|
- Standardized coding conventions
|
|
|
|
### 📦 **Dependencies & Compatibility**
|
|
|
|
#### 📌 **New Optional Dependencies**
|
|
- `python-dotenv`: For enhanced environment variable management
|
|
- Maintained backward compatibility - all dependencies remain optional
|
|
|
|
#### 🔄 **Python Version Support**
|
|
- Continued support for Python 3.8, 3.9, 3.10, 3.11, 3.12
|
|
- Enhanced async/await compatibility
|
|
- Cross-platform stability improvements
|
|
|
|
### 🚀 **Migration Guide**
|
|
|
|
#### ✅ **For Existing Users**
|
|
1. **No Breaking Changes**: All existing code continues to work without modifications
|
|
2. **Optional Enhancements**: Consider adding `.env` file for API key management
|
|
3. **New Examples**: Explore new example files for advanced usage patterns
|
|
4. **Import Compatibility**: All existing imports remain functional
|
|
|
|
#### 📝 **Recommended Updates**
|
|
```python
|
|
# Before (still works)
|
|
from zai import ZaiClient
|
|
client = ZaiClient(api_key="your-key")
|
|
|
|
# Enhanced (recommended)
|
|
import os
|
|
from zai import ZaiClient
|
|
from dotenv import load_dotenv
|
|
|
|
load_dotenv()
|
|
api_key = os.getenv('ZAI_API_KEY')
|
|
client = ZaiClient(api_key=api_key)
|
|
```
|
|
|
|
### 🔮 **What's Coming Next**
|
|
|
|
- Additional video generation models and features
|
|
- Enhanced streaming capabilities for all APIs
|
|
- More agent templates and scenarios
|
|
- Performance optimizations for large-scale usage
|
|
- Extended tool integrations
|
|
|
|
---
|
|
|
|
## v0.0.1a1 - Initial Release (2025-07-14)
|
|
|
|
🎉 **Welcome to the first release of the Z.ai Python SDK!**
|
|
|
|
This initial release provides comprehensive access to Z.ai's powerful AI capabilities through a modern, type-safe Python SDK.
|
|
|
|
### ✨ Core Features
|
|
|
|
#### 🤖 **Chat Completions**
|
|
- **Standard Chat**: Create chat completions with various models including `glm-4`, `charglm-3`
|
|
- **Streaming Support**: Real-time streaming responses for interactive applications
|
|
- **Tool Calling**: Function calling capabilities for enhanced AI interactions
|
|
- **Character Role-Playing**: Support for character-based conversations with `charglm-3` model
|
|
- **Multimodal Chat**: Image understanding capabilities with vision models
|
|
|
|
#### 🧠 **Embeddings**
|
|
- **Text Embeddings**: Generate high-quality vector embeddings for text
|
|
- **Configurable Dimensions**: Customizable embedding dimensions
|
|
- **Batch Processing**: Support for multiple inputs in a single request
|
|
|
|
#### 🎥 **Video Generation**
|
|
- **Text-to-Video**: Generate videos from text prompts
|
|
- **Image-to-Video**: Create videos from image inputs
|
|
- **Customizable Parameters**: Control quality, duration, FPS, and size
|
|
- **Audio Support**: Optional audio generation for videos
|
|
|
|
#### 🎵 **Audio Processing**
|
|
- **Speech Transcription**: Convert audio files to text
|
|
- **Multiple Formats**: Support for various audio file formats
|
|
|
|
#### 🤝 **Assistant API**
|
|
- **Conversation Management**: Structured conversation handling
|
|
- **Streaming Conversations**: Real-time assistant interactions
|
|
- **Metadata Support**: Rich conversation context and user information
|
|
|
|
#### 🔧 **Advanced Tools**
|
|
- **Web Search**: Integrated web search capabilities
|
|
- **File Management**: Upload, download, and manage files
|
|
- **Batch Operations**: Efficient batch processing for multiple requests
|
|
- **Knowledge Base**: Knowledge management and retrieval
|
|
- **Content Moderation**: Built-in content safety and moderation
|
|
- **Image Generation**: AI-powered image creation
|
|
- **Fine-tuning**: Custom model training capabilities
|
|
|
|
### 🛡️ **Developer Experience**
|
|
|
|
#### **Type Safety**
|
|
- Complete type annotations for all APIs
|
|
- Full IDE support with autocomplete and type checking
|
|
- Pydantic-based request/response validation
|
|
|
|
#### **Error Handling**
|
|
- Comprehensive error types for different failure scenarios
|
|
- Detailed error messages and debugging information
|
|
- Automatic retry mechanisms with configurable settings
|
|
|
|
#### **Performance & Reliability**
|
|
- Built-in connection pooling and request optimization
|
|
- Configurable timeout and retry strategies
|
|
- Efficient resource management
|
|
|
|
#### **Security**
|
|
- Secure API key management
|
|
- Optional token caching with security controls
|
|
- Built-in authentication handling
|
|
|
|
### 📋 **Technical Specifications**
|
|
|
|
#### **Python Support**
|
|
- **Python Versions**: 3.8, 3.9, 3.10, 3.11, 3.12
|
|
- **Async Support**: Full async/await compatibility
|
|
- **Cross-platform**: Windows, macOS, Linux support
|
|
|
|
#### **Dependencies**
|
|
- `httpx` (≥0.23.0): Modern HTTP client
|
|
- `pydantic` (≥1.9.0, <3.0): Data validation and serialization
|
|
- `typing-extensions` (≥4.0.0): Enhanced type hints
|
|
- `cachetools` (≥4.2.2): Caching utilities
|
|
- `pyjwt` (~2.8.0): JWT token handling
|
|
|
|
### 🚀 **Getting Started**
|
|
|
|
```bash
|
|
pip install zai-sdk
|
|
```
|
|
|
|
```python
|
|
from zai import ZaiClient
|
|
|
|
# Initialize client
|
|
client = ZaiClient(api_key="your-api-key")
|
|
|
|
# Create chat completion
|
|
response = client.chat.completions.create(
|
|
model="glm-4",
|
|
messages=[{"role": "user", "content": "Hello, Z.ai!"}]
|
|
)
|
|
|
|
print(response.choices[0].message.content)
|
|
```
|
|
|
|
### 📚 **Documentation & Support**
|
|
|
|
- **Documentation**: [Z.ai Open Platform](https://docs.z.ai/)
|
|
- **Examples**: Comprehensive examples in the `/examples` directory
|
|
- **Community**: GitHub Issues and Discussions
|
|
- **Contact**: user_feedback@z.ai
|
|
|
|
### 🔮 **What's Next**
|
|
|
|
This initial release establishes the foundation for Z.ai's Python SDK. Future releases will include:
|
|
- Additional model support
|
|
- Enhanced streaming capabilities
|
|
- More advanced tool integrations
|
|
- Performance optimizations
|
|
- Extended documentation and examples
|
|
|
|
---
|
|
|
|
## Migration Guide
|
|
|
|
### From v0.0.1a1 to v0.0.1b2
|
|
*No breaking changes - all existing code continues to work!*
|
|
|
|
**Optional Enhancements:**
|
|
1. Add `.env` file support for better API key management
|
|
2. Explore new example files for advanced usage patterns
|
|
3. Consider using the new agent invocation examples
|
|
4. Try the comprehensive video generation examples
|
|
|
|
For future versions, detailed migration guides will be provided here to help you upgrade smoothly.
|
|
|
|
---
|
|
|
|
**Note**: This release significantly enhances the developer experience while maintaining full backward compatibility. All improvements are additive, ensuring your existing code continues to work seamlessly. |