karrio-cli 2025.5rc3__py3-none-any.whl

karrio_cli/__main__.py

@@ -0,0 +1,105 @@
+import typer
+import karrio_cli.commands.sdk as sdk
+import karrio_cli.resources.logs as logs
+import karrio_cli.commands.login as login
+import karrio_cli.resources.orders as orders
+import karrio_cli.resources.events as events
+import karrio_cli.commands.codegen as codegen
+import karrio_cli.resources.trackers as trackers
+import karrio_cli.resources.carriers as carriers
+import karrio_cli.resources.shipments as shipments
+import karrio_cli.resources.connections as connections
+
+try:
+    import google.adk
+    import karrio_cli.ai.commands as agent
+    has_ai_dep = True
+except ImportError:
+    has_ai_dep = False
+
+try:
+    import karrio
+    import karrio_cli.commands.plugins as plugins
+    has_sdk_dep = True
+except ImportError:
+    has_sdk_dep = False
+
+app = typer.Typer()
+
+# Add login commands directly to the main app
+app.command()(login.login)
+app.command()(login.logout)
+app.command()(login.status)
+
+# Add resource-specific commands as sub-typers
+app.add_typer(
+    carriers.app,
+    name="carriers",
+    help="Manage carriers.",
+)
+
+app.add_typer(
+    connections.app,
+    name="connections",
+    help="Manage carrier connections.",
+)
+
+app.add_typer(
+    shipments.app,
+    name="shipments",
+    help="Manage shipments.",
+)
+
+app.add_typer(
+    trackers.app,
+    name="trackers",
+    help="Manage trackers.",
+)
+
+app.add_typer(
+    orders.app,
+    name="orders",
+    help="Manage orders.",
+)
+
+app.add_typer(
+    logs.app,
+    name="logs",
+    help="View API request logs.",
+)
+
+app.add_typer(
+    events.app,
+    name="events",
+    help="View system events.",
+)
+
+if has_sdk_dep:
+    app.add_typer(
+        sdk.app,
+        name="sdk",
+        help="SDK-related commands.",
+    )
+
+app.add_typer(
+    codegen.app,
+    name="codegen",
+    help="Code generation utilities.",
+)
+
+if has_sdk_dep:
+    app.add_typer(
+        plugins.app,
+        name="plugins",
+        help="Manage plugins.",
+    )
+
+if has_ai_dep:
+    app.add_typer(
+        agent.app,
+        name="agent",
+        help="Karrio AI agent.",
+    )
+
+if __name__ == "__main__":
+    app()

karrio_cli/ai/README.md

@@ -0,0 +1,335 @@
+# Karrio ADK Agent - Advanced Carrier Integration Generator
+
+A sophisticated AI agent system built with Google's Agent Development Kit (ADK) for generating 95% complete shipping carrier integrations for the Karrio platform.
+
+## 🚀 Features
+
+### Multi-Agent Architecture
+- **Schema Agent**: Converts API documentation to Python dataclasses with proper typing
+- **Mapping Agent**: Generates request/response mappings and transformations
+- **Testing Agent**: Creates comprehensive test suites with fixtures and mocks
+- **Integration Agent**: Orchestrates the complete integration process
+
+### RAG (Retrieval-Augmented Generation) System
+- **Pattern Extraction**: Analyzes 40+ existing Karrio connectors for best practices
+- **Semantic Search**: Finds similar implementations and code patterns
+- **Code Reuse**: Leverages proven patterns from existing integrations
+- **Quality Assurance**: Ensures consistency with Karrio standards
+
+### Comprehensive Generation
+- **Python Schemas**: Complete dataclass definitions with attrs and jstruct
+- **API Mappings**: Request/response transformations for all operations
+- **Authentication**: Support for various auth methods (API keys, OAuth, certificates)
+- **Error Handling**: Robust error processing and validation
+- **Test Suites**: Unit, integration, and performance tests
+- **Documentation**: Complete README, usage examples, and API reference
+- **Project Structure**: Proper directory organization and configuration files
+
+## 📁 Project Structure
+
+```
+modules/cli/karrio_cli/ai/
+├── README.md                          # This documentation
+├── karrio/                            # Main agent module
+│   ├── __init__.py                    # Module initialization
+│   ├── agent.py                       # Multi-agent architecture
+│   ├── rag_system.py                  # RAG implementation
+│   ├── SCHEMA_AGENT_PROMPT.md         # Schema agent instructions
+│   ├── MAPPING_AGENT_PROMPT.md        # Mapping agent instructions
+│   ├── TESTING_AGENT_PROMPT.md        # Testing agent instructions
+│   └── INTEGRATION_AGENT_PROMPT.md    # Integration agent instructions
+├── coomands.py                        # CLI commands
+└── test_agent.py                      # Comprehensive test suite
+```
+
+## 🛠️ Installation & Setup
+
+### Prerequisites
+- Python 3.8+
+- Google ADK installed (`pip install google-adk`)
+- Karrio CLI with development dependencies
+
+### Environment Setup
+1. Set your Google API key:
+   ```bash
+   export GOOGLE_API_KEY="your_api_key_here"
+   ```
+
+2. Optional: Configure for Vertex AI:
+   ```bash
+   export GOOGLE_GENAI_USE_VERTEXAI="TRUE"
+   ```
+
+### Verify Installation
+```bash
+cd modules/cli/karrio_cli/ai
+python test_agent.py
+```
+
+## 🎯 Usage
+
+### Launch the Web UI
+```bash
+karrio ai web
+```
+
+### Command Line Usage
+The agent can be used through the ADK CLI or integrated into your development workflow.
+
+### Generating a New Carrier Integration
+
+1. **Analysis Phase**: Study similar carriers
+   ```python
+   # Analyze existing patterns
+   analysis = analyze_existing_connector("ups", "all")
+
+   # Extract patterns from similar carriers
+   patterns = extract_carrier_patterns(
+       similar_carriers=["ups", "fedex", "canadapost"],
+       pattern_type="all"
+   )
+   ```
+
+2. **Schema Generation**: Convert API docs to Python
+   ```python
+   schema_result = generate_carrier_schema(
+       carrier_name="new_carrier",
+       api_documentation=json_schema,
+       schema_type="complete"
+   )
+   ```
+
+3. **Mapping Generation**: Create API transformations
+   ```python
+   mapping_result = generate_carrier_mappings(
+       carrier_name="new_carrier",
+       api_endpoints=endpoints,
+       operation_type="complete"
+   )
+   ```
+
+4. **Test Generation**: Build comprehensive test suite
+   ```python
+   test_result = generate_integration_tests(
+       carrier_name="new_carrier",
+       test_data=test_config,
+       test_type="complete"
+   )
+   ```
+
+5. **Final Assembly**: Create complete integration
+   ```python
+   integration = assemble_complete_integration(
+       carrier_name="new_carrier",
+       integration_config=config
+   )
+   ```
+
+## 🧠 RAG System
+
+### Pattern Recognition
+The RAG system automatically indexes and analyzes:
+
+- **Authentication Patterns**: API keys, OAuth, certificates
+- **Mapping Patterns**: Request/response transformations
+- **Schema Patterns**: Data model definitions
+- **Error Handling**: Exception processing and validation
+- **Testing Patterns**: Test structures and mock data
+
+### Similarity Detection
+Finds carriers with similar characteristics:
+- API type (REST, SOAP, GraphQL)
+- Authentication methods
+- Supported operations
+- Data formats
+- Geographic coverage
+
+### Code Examples
+Extracts working code examples from existing connectors:
+- Rate calculation functions
+- Shipment creation workflows
+- Tracking implementations
+- Error handling patterns
+
+## 🏗️ Agent Architecture
+
+### Schema Agent
+**Responsibility**: Convert API documentation to Python dataclasses
+- JSON schema parsing
+- Type annotation generation
+- attrs/jstruct integration
+- Karrio convention compliance
+
+### Mapping Agent
+**Responsibility**: Create API request/response mappings
+- Request transformation
+- Response parsing
+- Authentication handling
+- Error processing
+- Unit conversions
+
+### Testing Agent
+**Responsibility**: Generate comprehensive test suites
+- Unit test creation
+- Integration test scenarios
+- Mock data generation
+- Performance benchmarks
+- Error case coverage
+
+### Integration Agent
+**Responsibility**: Orchestrate complete integration assembly
+- Pattern analysis
+- Component coordination
+- Quality validation
+- Project structure
+- Documentation generation
+
+## 📊 Quality Standards
+
+### Completion Criteria
+- ✅ **95% Functional Completeness**: All major operations implemented
+- ✅ **90% Test Coverage**: Comprehensive test suite
+- ✅ **Zero Critical Issues**: No blocking problems
+- ✅ **Documentation Complete**: All required documentation present
+- ✅ **Pattern Compliance**: Follows established Karrio patterns
+
+### Code Quality
+- **Type Safety**: Full type annotations with mypy compliance
+- **Error Handling**: Robust exception processing
+- **Performance**: Optimized for production use
+- **Maintainability**: Clean, documented code
+- **Testing**: Comprehensive test coverage
+
+## 🧪 Testing
+
+### Run All Tests
+```bash
+python test_agent.py
+```
+
+### Test Categories
+- **RAG System Tests**: Pattern extraction and search
+- **Tool Function Tests**: Individual agent capabilities
+- **Integration Tests**: End-to-end workflows
+- **Quality Tests**: Code standards and compliance
+
+### Expected Output
+```
+🚀 Starting Karrio ADK Agent Tests
+=== Testing RAG System ===
+Found 25 authentication patterns
+Found 43 mapping patterns
+Found 31 schema patterns
+✅ RAG system tests passed
+
+=== Testing Connector Analysis ===
+UPS analysis completed for carrier: ups
+Found 147 files
+✅ Connector analysis tests passed
+
+📊 Test Results: 8 passed, 0 failed
+🎉 All tests passed! The ADK agent is ready for use.
+```
+
+## 🔧 Customization
+
+### Adding New Pattern Types
+1. Extend the RAG system in `rag_system.py`
+2. Add pattern recognition logic
+3. Update agent prompts
+4. Add tool functions
+
+### Custom Templates
+1. Add templates to `modules/cli/karrio_cli/templates/`
+2. Update template integration in agent tools
+3. Test with existing carriers
+
+### Agent Prompts
+Each agent has a dedicated prompt file:
+- `SCHEMA_AGENT_PROMPT.md`: Schema generation instructions
+- `MAPPING_AGENT_PROMPT.md`: Mapping creation guidance
+- `TESTING_AGENT_PROMPT.md`: Test generation standards
+- `INTEGRATION_AGENT_PROMPT.md`: Integration orchestration
+
+## 📈 Performance
+
+### RAG System Metrics
+- **Index Size**: ~40 carrier connectors analyzed
+- **Pattern Count**: 200+ identified patterns
+- **Search Speed**: <100ms for pattern queries
+- **Memory Usage**: ~50MB for full knowledge base
+
+### Generation Speed
+- **Schema Generation**: 2-5 seconds
+- **Mapping Generation**: 5-10 seconds
+- **Test Generation**: 3-7 seconds
+- **Complete Integration**: 15-30 seconds
+
+## 🤝 Contributing
+
+### Development Setup
+1. Clone the repository
+2. Install dependencies: `pip install -r requirements.dev.txt`
+3. Set up pre-commit hooks
+4. Run tests: `python test_agent.py`
+
+### Adding New Carriers
+1. Use the agent to generate 95% of the integration
+2. Test with real API credentials
+3. Add carrier-specific customizations
+4. Submit pull request with tests
+
+### Improving Patterns
+1. Analyze new carrier implementations
+2. Update RAG system with findings
+3. Enhance agent prompts
+4. Test with existing carriers
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**ImportError: No module named 'google.adk'**
+```bash
+pip install google-adk
+```
+
+**RAG system not finding patterns**
+- Ensure connectors directory exists
+- Check file permissions
+- Verify Python file syntax
+
+**Agent generation errors**
+- Check API key configuration
+- Verify input parameters
+- Review error logs
+
+### Debug Mode
+Enable verbose logging:
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## 📚 Resources
+
+- [Karrio Documentation](https://docs.karrio.io)
+- [Google ADK Documentation](https://developers.google.com/adk)
+- [Existing Carrier Examples](../../connectors/)
+- [CLI Templates](../templates/)
+
+## 📄 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](../../../../LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Karrio community for connector patterns
+- Google ADK team for the agent framework
+- Contributors to existing carrier integrations
+
+---
+
+**Ready to generate your first carrier integration?** 🚀
+
+Try: `karrio ai web` and follow the interactive prompts!

karrio_cli/ai/commands.py

@@ -0,0 +1,102 @@
+import os
+import sys
+import typer
+import subprocess
+import decouple
+from pathlib import Path
+
+app = typer.Typer()
+
+# Find the workspace root (where .env should be located)
+# Work relative to current working directory instead of going up levels
+current_file = Path(__file__).resolve()
+current_working_dir = Path.cwd()  # This will be the patch directory
+workspace_root = current_working_dir  # Use current directory as workspace root
+
+# Look for .env files in multiple locations (prioritizing current working directory)
+env_locations = [
+    workspace_root / ".env",  # Current working directory .env (patch/.env)
+    current_file.parent / ".env",  # Local AI directory .env
+    workspace_root / ".env.local",  # Alternative naming in current dir
+]
+
+# Find the first existing .env file
+env_file = None
+for location in env_locations:
+    if location.exists():
+        env_file = location
+        break
+
+# Configure decouple to use the found .env file or system environment
+if env_file:
+    config = decouple.Config(decouple.RepositoryEnv(str(env_file)))
+    print(f"Loading environment from: {env_file}")
+else:
+    config = decouple.AutoConfig()  # Use AutoConfig instead of RepositoryEnv without source
+    print("No .env file found, using system environment variables only")
+
+@app.command()
+def web():
+    """
+    Launches the Karrio AI agent web UI.
+    This function loads environment variables, and then uses the `adk` command-line
+    tool to start the agent's web UI.
+    """
+    # Load environment variables using python-decouple
+    google_api_key = config('GOOGLE_API_KEY', default='YOUR_API_KEY_HERE')
+    google_genai_use_vertexai = config('GOOGLE_GENAI_USE_VERTEXAI', default='FALSE')
+
+    # Verify API key is properly set
+    if google_api_key == 'YOUR_API_KEY_HERE':
+        print("❌ Error: GOOGLE_API_KEY not found!")
+        print(f"📍 Searched for .env files in:")
+        for location in env_locations:
+            exists = "✅" if location.exists() else "❌"
+            print(f"   {exists} {location}")
+        print("\n💡 To fix this:")
+        print(f"   1. Create a .env file in: {workspace_root}")
+        print("   2. Add your Google API key: GOOGLE_API_KEY=your_actual_api_key_here")
+        print("   3. Get an API key from: https://console.cloud.google.com/apis/credentials")
+        sys.exit(1)
+    else:
+        # Mask the API key for security when displaying
+        masked_key = google_api_key[:8] + "..." + google_api_key[-4:] if len(google_api_key) > 12 else "***"
+        print(f"✅ Google API Key loaded: {masked_key}")
+
+    # Prepare environment for the ADK process
+    env = os.environ.copy()  # Copy current environment
+    env['GOOGLE_API_KEY'] = google_api_key
+    env['GOOGLE_GENAI_USE_VERTEXAI'] = google_genai_use_vertexai
+
+    # Debug: Show environment variables being passed
+    print(f"🔧 Environment variables for ADK:")
+    print(f"   GOOGLE_API_KEY: {google_api_key[:8]}...{google_api_key[-4:] if len(google_api_key) > 12 else '***'}")
+    print(f"   GOOGLE_GENAI_USE_VERTEXAI: {google_genai_use_vertexai}")
+
+    # The `adk` command expects to be run from the parent of the agent module
+    agent_module_parent_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+
+    # The agent directory path (not module name)
+    agent_dir = os.path.join(agent_module_parent_dir, 'ai')
+
+    command = [
+        "adk",
+        "web",
+        agent_dir,
+    ]
+
+    try:
+        # Run the adk command with explicit environment
+        print(f"Running agent from: {agent_module_parent_dir}")
+        print(f"Using agent directory: {agent_dir}")
+        subprocess.run(command, check=True, cwd=agent_module_parent_dir, env=env)
+    except FileNotFoundError:
+        print("Error: 'adk' command not found.")
+        print("Please ensure the Google Agent Development Kit is installed ('pip install karrio-cli[dev]') and in your PATH.")
+        sys.exit(1)
+    except subprocess.CalledProcessError as e:
+        print(f"Error running agent: {e}")
+        sys.exit(1)
+
+if __name__ == '__main__':
+    app()

karrio_cli/ai/karrio_ai/__init__.py

@@ -0,0 +1 @@
+from karrio_ai import agent