primethink-cli 1.0.0__tar.gz

primethink_cli-1.0.0/DEVELOPER.md

@@ -0,0 +1,500 @@
+# PrimeThink CLI - Developer Guide
+
+## Table of Contents
+
+1. [Development Setup](#development-setup)
+2. [Project Structure](#project-structure)
+3. [Architecture](#architecture)
+4. [Adding New Commands](#adding-new-commands)
+5. [Testing](#testing)
+6. [Code Style](#code-style)
+7. [Contributing](#contributing)
+8. [Release Process](#release-process)
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.7 or higher
+- pip (Python package installer)
+- git
+
+### Clone and Install
+
+```bash
+# Clone the repository
+git clone https://github.com/primethink-ai/primethink-cli.git
+cd primethink-cli
+
+# Create a virtual environment (recommended)
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode
+pip install -e ".[dev]"
+```
+
+### Development Dependencies
+
+The development dependencies include:
+
+- `pytest` - Testing framework
+- `pytest-cov` - Code coverage plugin
+- `click` - CLI framework
+- `requests` - HTTP library
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Project Structure
+
+```
+primethink-cli/
+├── primethink.py           # Main CLI implementation
+├── setup.py                # Package configuration
+├── requirements.txt        # Runtime dependencies
+├── requirements-dev.txt    # Development dependencies
+├── README.md               # User documentation
+├── SPECS.md                # API specifications
+├── DEVELOPER.md            # This file
+├── USER_GUIDE.md           # User guide
+├── INTEGRATION_PAGE_TEXT.md # Integration documentation
+├── .gitignore              # Git ignore rules
+├── pytest.ini              # Pytest configuration
+├── Makefile                # Build and test commands
+├── docs/                   # Documentation files
+│   ├── openapi.json        # OpenAPI specification
+│   └── primethink_help_llms.txt  # API help text
+└── tests/                  # Test suite
+    ├── __init__.py
+    └── test_cli.py         # CLI tests
+```
+
+## Architecture
+
+### Core Components
+
+#### 1. Configuration Management
+
+The CLI uses a JSON-based configuration system stored in `~/.primethink/config.json`.
+
+**Config Structure**:
+```python
+{
+    "active_profile": "default",
+    "profiles": {
+        "profile_name": {
+            "token": "api_token",
+            "env": "prod"  # or "dev"
+        }
+    }
+}
+```
+
+**Key Functions**:
+- `load_config()`: Loads configuration from disk
+- `save_config(config)`: Saves configuration to disk
+- `get_active_config()`: Returns the active profile's configuration
+
+#### 2. Command Structure
+
+The CLI uses Click framework for command definition. Each command follows this pattern:
+
+```python
+@cli.command()
+@click.option('--param', '-p', required=True, help='Parameter description')
+def command_name(param):
+    """Command description."""
+    config = get_active_config()
+    api_url = ENVIRONMENTS[config['env']]
+    token = config['token']
+
+    # Make API request
+    response = requests.method(
+        f"{api_url}/endpoint",
+        headers={"Authorization": f"Token {token}"}
+    )
+
+    # Handle response
+    if response.status_code == 200:
+        click.echo(json.dumps(response.json(), indent=2))
+    else:
+        click.echo(f"Error: {response.status_code}")
+        sys.exit(1)
+```
+
+#### 3. API Client
+
+The CLI uses the `requests` library for HTTP communication with the PrimeThink API.
+
+**Authentication**:
+```python
+headers = {
+    "Authorization": f"Token {token}",
+    "accept": "application/json"
+}
+```
+
+**File Uploads**:
+```python
+files_data = []
+for file_path in files:
+    files_data.append(('files', open(file_path, 'rb')))
+
+response = requests.post(
+    url,
+    data=form_data,
+    files=files_data
+)
+
+# Always close file handles
+for _, file_handle in files_data:
+    file_handle.close()
+```
+
+## Adding New Commands
+
+### Step 1: Define the Command
+
+Add a new command decorator and function in `primethink.py`:
+
+```python
+@cli.command()
+@click.argument('required_arg')
+@click.option('--optional', '-o', help='Optional parameter')
+def new_command(required_arg, optional):
+    """Brief description of what the command does."""
+    config = get_active_config()
+    api_url = ENVIRONMENTS[config['env']]
+    token = config['token']
+
+    try:
+        response = requests.get(
+            f"{api_url}/api/v1/your-endpoint",
+            headers={
+                "Authorization": f"Token {token}",
+                "accept": "application/json"
+            }
+        )
+
+        if response.status_code == 200:
+            result = response.json()
+            click.echo(json.dumps(result, indent=2))
+        else:
+            click.echo(f"Error: {response.status_code} - {response.text}")
+            sys.exit(1)
+    except requests.exceptions.RequestException as e:
+        click.echo(f"Error connecting to API: {e}")
+        sys.exit(1)
+```
+
+### Step 2: Add Tests
+
+Create test cases in `tests/test_cli.py`:
+
+```python
+@patch('primethink.get_active_config')
+@patch('primethink.requests.get')
+def test_new_command(mock_get, mock_config_fn, runner):
+    """Test new_command."""
+    mock_config_fn.return_value = {'token': 'test-token', 'env': 'prod'}
+
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.json.return_value = {'result': 'success'}
+    mock_get.return_value = mock_response
+
+    result = runner.invoke(new_command, ['arg1', '--optional', 'value'])
+
+    assert result.exit_code == 0
+    mock_get.assert_called_once()
+    assert 'success' in result.output
+```
+
+### Step 3: Update Documentation
+
+Update the following files:
+- `README.md` - Add command to usage examples
+- `SPECS.md` - Add API endpoint specification
+- `USER_GUIDE.md` - Add user-friendly guide for the command
+
+### Step 4: Run Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with verbose output
+pytest -v
+
+# Run specific test file
+pytest tests/test_cli.py
+
+# Run specific test
+pytest tests/test_cli.py::test_configure_command
+
+# Run with coverage
+pytest --cov=primethink --cov-report=html
+```
+
+### Test Structure
+
+Tests use the following tools:
+- `pytest` - Test framework
+- `click.testing.CliRunner` - CLI testing
+- `unittest.mock` - Mocking dependencies
+
+### Writing Tests
+
+Example test pattern:
+
+```python
+def test_command(runner, mock_config):
+    """Test description."""
+    # Arrange
+    with patch('primethink.load_config') as mock_load:
+        mock_load.return_value = mock_config
+
+        # Act
+        result = runner.invoke(command_name, ['arg'])
+
+        # Assert
+        assert result.exit_code == 0
+        assert 'expected output' in result.output
+```
+
+### Mocking API Responses
+
+```python
+@patch('primethink.requests.post')
+def test_api_call(mock_post, runner):
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.json.return_value = {'data': 'value'}
+    mock_post.return_value = mock_response
+
+    # Test implementation
+```
+
+## Code Style
+
+### Python Style Guide
+
+Follow PEP 8 guidelines:
+
+- Use 4 spaces for indentation
+- Maximum line length: 100 characters
+- Use descriptive variable names
+- Add docstrings to all functions
+
+### Naming Conventions
+
+- **Functions**: `snake_case`
+- **Classes**: `PascalCase`
+- **Constants**: `UPPER_SNAKE_CASE`
+- **Private methods**: `_leading_underscore`
+
+### Documentation
+
+- Add docstrings to all public functions
+- Use type hints where appropriate
+- Keep comments concise and meaningful
+
+Example:
+
+```python
+def get_active_config() -> Dict[str, str]:
+    """Get active profile configuration.
+
+    Returns:
+        Dict containing 'token' and 'env' keys.
+
+    Raises:
+        SystemExit: If no active profile is configured.
+    """
+    config = load_config()
+    # Implementation
+```
+
+## Contributing
+
+### Workflow
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Write tests for new functionality
+5. Ensure all tests pass: `pytest`
+6. Commit your changes: `git commit -m "Add my feature"`
+7. Push to your fork: `git push origin feature/my-feature`
+8. Create a Pull Request
+
+### Pull Request Guidelines
+
+- Include a clear description of changes
+- Reference any related issues
+- Ensure all tests pass
+- Update documentation as needed
+- Add tests for new features
+
+### Code Review Process
+
+All pull requests require:
+- At least one approval
+- Passing CI/CD checks
+- Updated documentation
+- Code coverage maintained or improved
+
+## Release Process
+
+### Version Numbering
+
+Follow Semantic Versioning (SemVer):
+- **MAJOR**: Breaking changes
+- **MINOR**: New features (backward compatible)
+- **PATCH**: Bug fixes (backward compatible)
+
+### Release Checklist
+
+1. Update version in `setup.py`
+2. Update `CHANGELOG.md`
+3. Run full test suite: `pytest`
+4. Build package: `python setup.py sdist bdist_wheel`
+5. Test installation in clean environment
+6. Tag release: `git tag v1.0.0`
+7. Push tags: `git push --tags`
+8. Publish to PyPI: `twine upload dist/*`
+
+### Build Commands
+
+```bash
+# Clean previous builds
+rm -rf build dist *.egg-info
+
+# Build distribution packages
+python setup.py sdist bdist_wheel
+
+# Test package installation
+pip install dist/primethink_cli-1.0.0-py3-none-any.whl
+```
+
+## Debugging
+
+### Enable Verbose Output
+
+Set debug environment variable:
+
+```bash
+export PRIMETHINK_DEBUG=1
+primethink command
+```
+
+### Common Issues
+
+#### Import Errors
+
+```bash
+# Reinstall in development mode
+pip install -e .
+```
+
+#### Config File Issues
+
+```bash
+# Check config location
+cat ~/.primethink/config.json
+
+# Reset config
+rm ~/.primethink/config.json
+primethink configure --token YOUR_TOKEN
+```
+
+#### API Errors
+
+```bash
+# Test with curl
+curl -X GET \
+  'https://api.primethink.ai/api/v1/tasks/available_task_actions' \
+  -H 'Authorization: Token YOUR_TOKEN'
+```
+
+## Performance Considerations
+
+### File Handling
+
+Always close file handles after upload:
+
+```python
+files_data = []
+for file_path in files:
+    files_data.append(('files', open(file_path, 'rb')))
+
+try:
+    response = requests.post(url, files=files_data)
+finally:
+    for _, file_handle in files_data:
+        file_handle.close()
+```
+
+### Request Timeout
+
+Set reasonable timeouts for API requests:
+
+```python
+response = requests.get(url, timeout=30)
+```
+
+### Memory Usage
+
+For large files, consider streaming:
+
+```python
+with open(file_path, 'rb') as f:
+    files = {'file': f}
+    response = requests.post(url, files=files)
+```
+
+## Security Best Practices
+
+1. **Never log API tokens**
+2. **Use environment variables for sensitive data**
+3. **Validate user inputs**
+4. **Sanitize file paths**
+5. **Use HTTPS for all API calls**
+6. **Store config with restricted permissions**
+
+```python
+# Set secure permissions on config file
+import os
+os.chmod(CONFIG_FILE, 0o600)
+```
+
+## Resources
+
+- [Click Documentation](https://click.palletsprojects.com/)
+- [Requests Documentation](https://requests.readthedocs.io/)
+- [Pytest Documentation](https://docs.pytest.org/)
+- [PrimeThink API Documentation](https://docs.primethink.ai/)
+- [PEP 8 Style Guide](https://pep8.org/)
+
+## Support
+
+For development questions or issues:
+- Open an issue on GitHub
+- Email: support@primethink.ai
+- Join our developer community
+
+## License
+
+This project is licensed under the MIT License. See LICENSE file for details.

primethink_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PrimeThink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

primethink_cli-1.0.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include SPECS.md
+include USER_GUIDE.md
+include DEVELOPER.md
+recursive-include docs *.md *.txt
+recursive-include install *.sh *.ps1 *.cmd *.rb
+recursive-include scripts *.sh
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store