zenoo-rpc 0.2.2

A zen-like, modern async Python library for Odoo RPC with type safety, transactions, caching, and AI-powered MCP integration

Zenoo RPC

A zen-like, modern async Python library for Odoo RPC with type safety, AI integration, and MCP protocol support

📚 Documentation • 🚀 Quick Start • 📦 PyPI • 🐛 Issues • 💬 Discussions

🚀 Why Zenoo RPC?

Zenoo RPC is a next-generation Python library designed to replace odoorpc with modern Python practices and superior performance. Built from the ground up with async/await, type safety, and developer experience in mind.

"Zen" - Simple, elegant, and intuitive API design
"oo" - Object-oriented with Odoo integration
"RPC" - Remote Procedure Call excellence

✨ Key Features

• 🔄 Async-First: Built with asyncio and httpx for high-performance concurrent operations
• 🛡️ Type Safety: Full Pydantic integration with IDE support and runtime validation
• 🎯 Fluent API: Intuitive, chainable query builder that feels natural
• 🤖 AI-Powered: Natural language queries, error diagnosis, and code generation
• 🔌 MCP Integration: Full Model Context Protocol support for AI assistants (Claude Desktop, ChatGPT)
• ⚡ Performance: Intelligent caching, batch operations, and optimized RPC calls
• 🔧 Modern Python: Leverages Python 3.8+ features with proper type hints
• 📦 Clean Architecture: Well-structured, testable, and maintainable codebase
• 🔄 Transaction Support: ACID-compliant transactions with rollback capabilities
• 🚀 Batch Operations: Efficient bulk operations for high-performance scenarios
• 🔁 Retry Mechanisms: Intelligent retry with exponential backoff and circuit breaker
• 💾 Intelligent Caching: TTL/LRU caching with Redis support

🤔 Problems with odoorpc

• Synchronous only: No async support for modern Python applications
• No type safety: Raw dictionaries and lists without validation
• Chatty API: Multiple RPC calls for simple operations (search + browse)
• Complex relationship handling: Requires knowledge of Odoo's tuple commands
• Poor error handling: Generic exceptions without context
• No caching: Repeated calls for the same data

🎯 Zenoo RPC Solutions

# odoorpc (old way)
Partner = odoo.env['res.partner']
partner_ids = Partner.search([('is_company', '=', True)], limit=10)
partners = Partner.browse(partner_ids)  # Second RPC call!

# Zenoo RPC (modern way)
async with ZenooClient("localhost", port=8069) as client:
    await client.login("demo", "admin", "admin")

    partners = await client.model(ResPartner).filter(
        is_company=True
    ).limit(10).all()  # Single RPC call with type safety!

📦 Installation

From PyPI (Recommended)

pip install zenoo-rpc

With Optional Dependencies

# For Redis caching support
pip install zenoo-rpc[redis]

# For AI features (Gemini, OpenAI, Anthropic)
pip install zenoo-rpc[ai]

# For MCP integration (AI assistants)
pip install zenoo-rpc[mcp]

# For development
pip install zenoo-rpc[dev]

# All features
pip install zenoo-rpc[ai,mcp,redis,dev]

From Source

git clone https://github.com/tuanle96/zenoo-rpc.git
cd zenoo-rpc
pip install -e .

🏗️ Architecture

Zenoo RPC follows modern Python best practices with a clean, modular architecture:

src/zenoo_rpc/
├── client.py              # Main async client
├── transport/             # HTTP transport layer
├── models/                # Pydantic models
├── query/                 # Fluent query builder
├── cache/                 # Async caching layer
├── exceptions/            # Structured exception hierarchy
├── transaction/           # Transaction management
├── batch/                 # Batch operations
├── retry/                 # Retry mechanisms
├── ai/                    # AI-powered features
├── mcp_server/            # Model Context Protocol server
├── mcp_client/            # Model Context Protocol client
└── utils/                 # Utilities and helpers

🚀 Quick Start

import asyncio
from zenoo_rpc import ZenooClient
from zenoo_rpc.models.common import ResPartner

async def main():
    async with ZenooClient("https://your-odoo-server.com") as client:
        # Authenticate
        await client.login("your_database", "your_username", "your_password")

        # Type-safe queries with IDE support
        partners = await client.model(ResPartner).filter(
            is_company=True,
            name__ilike="company%"
        ).limit(10).all()

        # Access fields with full type safety
        for partner in partners:
            print(f"Company: {partner.name} - Email: {partner.email}")

        # Transaction management (optional)
        await client.setup_transaction_manager()
        async with client.transaction():
            partner = await client.model(ResPartner).filter(
                is_company=True
            ).first()
            if partner:
                print(f"Processing: {partner.name}")
                # Modifications are committed automatically on context exit

if __name__ == "__main__":
    asyncio.run(main())

🔌 MCP Integration - AI Assistant Support

Zenoo RPC provides full Model Context Protocol (MCP) support, enabling seamless integration with AI assistants like Claude Desktop, ChatGPT, and other MCP-compatible tools.

🤖 Use with Claude Desktop

Configure Claude Desktop to use Zenoo RPC as an MCP server:

// ~/.config/claude/claude_desktop_config.json
{
  "mcpServers": {
    "odoo": {
      "command": "python",
      "args": ["-m", "zenoo_rpc.mcp_server.cli"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DATABASE": "demo",
        "ODOO_USERNAME": "admin",
        "ODOO_PASSWORD": "admin"
      }
    }
  }
}

Now Claude can directly interact with your Odoo data:

User: "Find all technology companies in Vietnam and analyze their sales"

Claude automatically:
1. Searches for companies with filters: is_company=True, country='Vietnam', name contains 'tech'
2. Retrieves their sales orders and analyzes performance
3. Provides insights and recommendations

🛠️ MCP Tools Available

• search_records - Advanced search with complex filters
• get_record - Retrieve specific records with relationships
• create_record - Create new records with validation
• update_record - Update existing records
• delete_record - Delete records safely
• complex_search - Advanced queries with Q objects
• batch_operation - High-performance bulk operations
• analytics_query - Data analysis and aggregation

🚀 Installation with MCP

# Install with MCP support
pip install zenoo-rpc[mcp]

# Start MCP server
python -m zenoo_rpc.mcp_server.cli --transport stdio

🎯 Advanced Features

Lazy Loading with Type Safety

# Relationship fields are lazy-loaded automatically
partner = await client.model(ResPartner).get(1)
company = await partner.company_id  # Loaded on demand
children = await partner.child_ids.all()  # Lazy collection

Intelligent Caching

async with ZenooClient("localhost", port=8069) as client:
    await client.login("demo", "admin", "admin")

    # Setup cache manager
    await client.setup_cache_manager(backend="redis", url="redis://localhost:6379/0")

    # Cached queries
    partners = await client.model(ResPartner).filter(
        is_company=True
    ).cache(ttl=300).all()  # Cached for 5 minutes

Batch Operations

async with ZenooClient("localhost", port=8069) as client:
    await client.login("demo", "admin", "admin")

    # Setup batch manager
    await client.setup_batch_manager(max_chunk_size=100)

    # Efficient bulk operations
    async with client.batch() as batch:
        partners_data = [
            {"name": "Company 1", "email": "[e-mail]"},
            {"name": "Company 2", "email": "[e-mail]"},
        ]
        partners = await batch.create_many(ResPartner, partners_data)

Transaction Management

async with ZenooClient("localhost", port=8069) as client:
    await client.login("demo", "admin", "admin")

    # Setup transaction manager
    await client.setup_transaction_manager()

    # ACID transactions with rollback
    async with client.transaction() as tx:
        partner = await client.model(ResPartner).create({
            "name": "Test Company",
            "email": "[e-mail]"
        })

        # If any error occurs, transaction is automatically rolled back
        await partner.update({"phone": "[phone]"})
        # Committed automatically on successful exit

🤖 AI-Powered Features

Zenoo RPC includes cutting-edge AI capabilities powered by LiteLLM and Google Gemini:

async with ZenooClient("localhost", port=8069) as client:
    await client.login("demo", "admin", "admin")

    # Setup AI capabilities
    await client.setup_ai(
        provider="gemini",
        model="gemini-2.5-flash-lite",
        api_key="your-gemini-api-key"
    )

    # Natural language queries
    partners = await client.ai.query("Find all companies in Vietnam with revenue > 1M USD")

    # Intelligent error diagnosis
    try:
        result = await client.search("invalid.model", [])
    except Exception as error:
        diagnosis = await client.ai.diagnose(error)
        print(f"Problem: {diagnosis['problem']}")
        print(f"Solution: {diagnosis['solution']}")

    # Smart code generation
    model_code = await client.ai.generate_model("res.partner")

    # Performance optimization suggestions
    suggestions = await client.ai.suggest_optimization(query_stats)

    # Interactive AI chat
    response = await client.ai.chat("How do I create a Many2one field in Odoo?")

AI Features:

• 🗣️ Natural Language Queries: Convert plain English to optimized Odoo queries
• 🔍 Error Diagnosis: AI-powered error analysis with actionable solutions
• 🏗️ Code Generation: Generate typed Python models from Odoo schemas
• ⚡ Performance Optimization: AI suggestions for query and cache optimization
• 💬 Interactive Chat: Get expert advice on Odoo development

Installation with AI:

pip install zenoo-rpc[ai]

🧪 Development Status

Zenoo RPC is currently in Alpha stage with active development. The core architecture is stable and functional, but we're continuously improving based on community feedback.

Current Status

• ✅ Core Features: Fully implemented and tested
• ✅ Type Safety: Complete Pydantic integration
• ✅ Async Operations: Full async/await support
• ✅ Advanced Features: Caching, transactions, batch operations
• ✅ Documentation: Comprehensive guides and examples
• 🔄 Community: Growing user base and contributors
• 🔄 Performance: Ongoing optimization efforts

Roadmap

• Phase 1: Core transport layer and async client
• Phase 2: Pydantic models and query builder foundation
• Phase 3: Advanced features (caching, transactions, batch ops)
• Phase 4: AI-powered features (natural language queries, error diagnosis, code generation)
• Phase 5: Documentation and community adoption
• Phase 6: Performance optimization and production hardening
• Phase 7: Advanced AI features (predictive analytics, auto-optimization)
• Phase 8: Plugin system and extensibility
• Phase 9: GraphQL support and modern APIs

Production Readiness

Zenoo RPC is being used in production environments, but we recommend:

• Testing: Thoroughly test in your specific environment
• Monitoring: Implement proper logging and monitoring
• Gradual Migration: Migrate from odoorpc incrementally
• Community Support: Join our discussions for help and feedback

Compatibility

• Python: 3.8, 3.9, 3.10, 3.11, 3.12
• Odoo: 18.0 (tested) - other versions compatibility not yet verified
• Operating Systems: Linux, macOS, Windows

🤝 Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing feedback, your contributions help make Zenoo RPC better for everyone.

Ways to Contribute

• 🐛 Report Bugs: Use our issue templates
• ✨ Request Features: Share your ideas in GitHub Discussions
• 📝 Improve Documentation: Help us make the docs clearer and more comprehensive
• 🧪 Write Tests: Increase test coverage and add edge cases
• 🔧 Fix Issues: Pick up issues labeled good first issue or help wanted
• 💡 Share Examples: Contribute real-world usage examples

Quick Development Setup

# Clone the repository
git clone https://github.com/tuanle96/zenoo-rpc.git
cd zenoo-rpc

# Install development dependencies
pip install -e ".[dev,redis]"

# Install pre-commit hooks (recommended)
pre-commit install

# Run tests
pytest

# Run quality checks
ruff check .
black .
mypy src/zenoo_rpc

# Build documentation locally
mkdocs serve

Contribution Guidelines

Please read our Contributing Guide for detailed information about:

• Code style and conventions
• Testing requirements
• Pull request process
• Issue reporting guidelines
• Community standards

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run quality checks (pre-commit run --all-files)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Getting Help

• 💬 GitHub Discussions: Ask questions and get help
• 📚 Documentation: Comprehensive guides and examples
• 🐛 Issues: Report bugs or request features

🛠️ Development

Want to contribute? Here's how to set up your development environment:

# Clone the repository
git clone https://github.com/tuanle96/zenoo-rpc.git
cd zenoo-rpc

# Install development dependencies
pip install -e ".[dev,redis]"

# Install pre-commit hooks (recommended)
pre-commit install

# Run tests
pytest

# Run quality checks
ruff check .
black .
mypy src/zenoo_rpc

📚 Documentation

• Getting Started: Installation and basic usage
• User Guide: Comprehensive feature documentation
• API Reference: Complete API documentation
• Migration Guide: Migrating from odoorpc
• Examples: Real-world usage examples

🐛 Support

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and community discussion
• Documentation: Comprehensive guides and API reference

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the need to modernize the Odoo Python ecosystem
• Built on the shoulders of giants: httpx, pydantic, and asyncio
• Thanks to the OCA team for maintaining odoorpc and showing us what to improve
• Special thanks to all contributors and early adopters

---

Zenoo RPC: Because your Odoo integrations deserve modern Python! 🐍✨

⭐ Star us on GitHub • 📦 Try it on PyPI • 📚 Read the Docs