mirror of
https://github.com/hanzoai/python-sdk.git
synced 2026-10-23 20:23:00 +00:00
zeekay
241ca6dc59
README: PyPI serves 3.2.1 and this tree is 3.2.11, so the install line is the git one. Between the two the default version left the operation ids — 3.2.1 carries get_v1_keys/get_v1_tools (182 api modules, 2172 models) and this carries get_keys/get_tools — so `pip install hanzoai` above a `get_keys()` quickstart hands the reader a client that cannot run it. Counts are measured off the pinned document: 1814 paths, 2479 operations, 191 tags + default_api = 192 API classes over 2460 models, 2659 importable modules. Auth was wrong everywhere and it was the same root cause: the document declares no securityScheme, so every operation got an empty auth_settings and Configuration(access_token=…) is read by nothing. Serializing get_keys from such a Configuration produces a request with no Authorization header at all — the five flows have been calling anonymously and reading the refusal as a bad key. examples/client.py now passes the bearer through ApiClient's header_name/value pair, verified against a local server that echoes what it received, and a smoke test pins both halves so the day cloud emits the scheme, the test fails and the header moves back into Configuration. The examples gate resolved class names and stopped there, which is how `money` and `tools` once passed it while every call in them named a method that no longer existed. It now walks the syntax tree for attribute accesses on anything bound to a *Api and asks the class: ten names resolve, and a stale get_v1_tools fails in the same second the import passes. Deleted five example scripts that imported hanzoai.Hanzo, hanzoai.cluster, hanzoai.agents and hanzoai.completion — none of which exist — or were dict literals captioned "in practice this would be called through the MCP interface"; compileall passed all five, because syntax is not a claim. Deleted three docs that were fabrication rather than drift and that nothing rendered: FEATURES.md, QUICKSTART.md, GPT5_ORCHESTRATION.md. pkg/hanzo-agent said `pip install hanzoai` and `from hanzoai import Agent, Runner`; the client has no Agent. Its own `full` extra resolved to hanzoai[web3,tee,marketplace,cli], extras the client does not declare, so it installed the client and none of the extensions. pyproject said BSD-3-Clause while LICENSE is the Apache 2.0 text. test_smoke imported tracker_api and no /v1/tracker path is emitted any more, so the suite carried a failing test naming a module the client does not have; it reads analytics_api now, off the client.
237 lines
5.1 KiB
Markdown
237 lines
5.1 KiB
Markdown
# Contributing to Hanzo Python SDK
|
|
|
|
We welcome contributions to the Hanzo Python SDK! This document provides guidelines for contributing to the project.
|
|
|
|
## Code of Conduct
|
|
|
|
By participating in this project, you agree to abide by our Code of Conduct:
|
|
- Be respectful and inclusive
|
|
- Welcome newcomers and help them get started
|
|
- Focus on constructive criticism
|
|
- Accept feedback gracefully
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.10 or higher
|
|
- `uv` package manager
|
|
- Git
|
|
|
|
### Development Setup
|
|
|
|
1. Fork the repository
|
|
2. Clone your fork:
|
|
```bash
|
|
git clone https://github.com/your-username/python-sdk.git
|
|
cd python-sdk
|
|
```
|
|
|
|
3. Install dependencies:
|
|
```bash
|
|
make setup
|
|
```
|
|
|
|
4. Create a feature branch:
|
|
```bash
|
|
git checkout -b feature/your-feature-name
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Code Style
|
|
|
|
We use `ruff` for linting and formatting:
|
|
|
|
```bash
|
|
# Format code
|
|
make format
|
|
|
|
# Check linting
|
|
make lint
|
|
|
|
# Type checking
|
|
make type-check
|
|
```
|
|
|
|
### Testing
|
|
|
|
All contributions must include tests:
|
|
|
|
```bash
|
|
# Run all tests
|
|
make test
|
|
|
|
# Run specific package tests
|
|
cd pkg/hanzo && pytest tests/
|
|
|
|
# Run with coverage
|
|
pytest tests/ --cov=hanzo --cov-report=html
|
|
```
|
|
|
|
### Documentation
|
|
|
|
- Update README files for any new features
|
|
- Add docstrings to all public functions/classes
|
|
- Include usage examples in docstrings
|
|
- Update API documentation if needed
|
|
|
|
## Contribution Process
|
|
|
|
### 1. Find or Create an Issue
|
|
|
|
- Check existing issues first
|
|
- Create a new issue for bugs or features
|
|
- Get feedback before starting major work
|
|
|
|
### 2. Make Changes
|
|
|
|
- Write clean, readable code
|
|
- Follow existing patterns and conventions
|
|
- Keep commits small and focused
|
|
- Write descriptive commit messages
|
|
|
|
### 3. Commit Guidelines
|
|
|
|
We follow conventional commits:
|
|
|
|
```
|
|
type(scope): description
|
|
|
|
[optional body]
|
|
|
|
[optional footer]
|
|
```
|
|
|
|
Types:
|
|
- `feat`: New feature
|
|
- `fix`: Bug fix
|
|
- `docs`: Documentation
|
|
- `style`: Code style changes
|
|
- `refactor`: Code refactoring
|
|
- `test`: Test changes
|
|
- `chore`: Build/tooling changes
|
|
|
|
Examples:
|
|
```bash
|
|
feat(agents): add parallel execution support
|
|
fix(mcp): resolve file permission issue
|
|
docs(network): update API documentation
|
|
```
|
|
|
|
### 4. Submit Pull Request
|
|
|
|
1. Push your branch:
|
|
```bash
|
|
git push origin feature/your-feature-name
|
|
```
|
|
|
|
2. Create a pull request on GitHub
|
|
|
|
3. Fill out the PR template:
|
|
- Describe what changes you made
|
|
- Link related issues
|
|
- Include test results
|
|
- Add screenshots if applicable
|
|
|
|
4. Wait for review and address feedback
|
|
|
|
## Package-Specific Guidelines
|
|
|
|
### The client (`pkg/hanzoai/cloud`)
|
|
- Generated. Never edit it by hand — a regeneration is `rmtree` + `copytree`, so
|
|
the edit is gone and CI's `generate.py --check` fails the run before that.
|
|
- A defect you find in generated code is fixed in the API document, where every
|
|
other language SDK gets the same fix.
|
|
- Method and class names are the document's operation ids, so they move when it
|
|
does. Note the rename in the commit; do not add an alias for the old name.
|
|
|
|
### CLI (`pkg/hanzo`)
|
|
- Keep commands intuitive
|
|
- Provide helpful error messages
|
|
- Include --help for all commands
|
|
|
|
### MCP (`pkg/hanzo-mcp`)
|
|
- Follow MCP specification
|
|
- Ensure tool safety
|
|
- Document permissions required
|
|
|
|
### Agents (`pkg/hanzo-agents`)
|
|
- Keep agents focused and specialized
|
|
- Provide clear agent descriptions
|
|
- Include usage examples
|
|
|
|
### Network (`pkg/hanzo-network`)
|
|
- Ensure thread safety
|
|
- Handle network failures gracefully
|
|
- Document resource requirements
|
|
|
|
## Testing Requirements
|
|
|
|
### Unit Tests
|
|
- Test individual functions/methods
|
|
- Mock external dependencies
|
|
- Aim for >80% coverage
|
|
|
|
### Integration Tests
|
|
- Test component interactions
|
|
- Use real services when possible
|
|
- Mark with `@pytest.mark.integration`
|
|
|
|
### End-to-End Tests
|
|
- Test complete workflows
|
|
- Run in CI/CD pipeline
|
|
- Document test scenarios
|
|
|
|
## Code Review Process
|
|
|
|
### What We Look For
|
|
|
|
- **Correctness**: Does it work as intended?
|
|
- **Tests**: Are there adequate tests?
|
|
- **Documentation**: Is it well-documented?
|
|
- **Style**: Does it follow our conventions?
|
|
- **Performance**: Are there any bottlenecks?
|
|
- **Security**: Are there security concerns?
|
|
|
|
### Review Timeline
|
|
|
|
- Initial review: Within 2-3 business days
|
|
- Follow-up reviews: Within 1-2 business days
|
|
- Small fixes: Same day if possible
|
|
|
|
## Release Process
|
|
|
|
1. **Version Bump**: Update version in `pyproject.toml`
|
|
2. **Changelog**: Update CHANGELOG.md
|
|
3. **Testing**: Run full test suite
|
|
4. **Documentation**: Update docs if needed
|
|
5. **Tag**: Create version tag
|
|
6. **Release**: Publish to PyPI
|
|
|
|
## Getting Help
|
|
|
|
### Resources
|
|
|
|
- [Documentation](https://docs.hanzo.ai)
|
|
- [Discord Community](https://discord.gg/CJCyAsm9Vr)
|
|
- [GitHub Discussions](https://github.com/hanzoai/python-sdk/discussions)
|
|
|
|
### Contact
|
|
|
|
- General questions: support@hanzo.ai
|
|
- Security issues: security@hanzo.ai
|
|
- Partnership: partners@hanzo.ai
|
|
|
|
## Recognition
|
|
|
|
Contributors are recognized in:
|
|
- CONTRIBUTORS.md file
|
|
- Release notes
|
|
- Project documentation
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the Apache License 2.0.
|
|
|
|
Thank you for contributing to Hanzo! 🎉 |