Skip to content

Commit c599e71

Browse files
arahanguaarahangua
committed
checkpoint: functionality checked
1 parent f696b1f commit c599e71

20 files changed

Lines changed: 2123 additions & 702 deletions

‎.github/workflows/ci.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main, develop ]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.11", "3.12"]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python ${{ matrix.python-version }}
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
24+
- name: Install uv
25+
uses: astral-sh/setup-uv@v3
26+
27+
- name: Install dependencies
28+
run: |
29+
uv pip install --system -e .
30+
uv pip install --system pytest pytest-asyncio pytest-cov
31+
32+
- name: Run linting
33+
run: |
34+
uv pip install --system ruff
35+
ruff check src/
36+
continue-on-error: true
37+
38+
- name: Run tests
39+
run: |
40+
pytest tests/ -v
41+
continue-on-error: true # Since we need CZero Engine running
42+
43+
- name: Check examples syntax
44+
run: |
45+
python -m py_compile examples/*.py

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ logs/
5757
Thumbs.db
5858

5959
# Project specific
60-
sample_docs/
60+
# Note: sample_docs/ is used by example 02_rag_system.py
6161
sample_project/
6262
batch_test/
6363
test_*/

‎CODE_OF_CONDUCT.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment:
18+
19+
* Using welcoming and inclusive language
20+
* Being respectful of differing viewpoints and experiences
21+
* Gracefully accepting constructive criticism
22+
* Focusing on what is best for the community
23+
* Showing empathy towards other community members
24+
25+
Examples of unacceptable behavior:
26+
27+
* The use of sexualized language or imagery, and sexual attention or advances
28+
* Trolling, insulting or derogatory comments, and personal or political attacks
29+
* Public or private harassment
30+
* Publishing others' private information without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate
32+
33+
## Enforcement Responsibilities
34+
35+
Community leaders are responsible for clarifying and enforcing our standards of
36+
acceptable behavior and will take appropriate and fair corrective action in
37+
response to any behavior that they deem inappropriate, threatening, offensive,
38+
or harmful.
39+
40+
## Scope
41+
42+
This Code of Conduct applies within all community spaces, and also applies when
43+
an individual is officially representing the community in public spaces.
44+
45+
## Enforcement
46+
47+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
48+
reported to the community leaders responsible for enforcement at info@czero.cc.
49+
50+
All complaints will be reviewed and investigated promptly and fairly.
51+
52+
## Attribution
53+
54+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
55+
version 2.1, available at
56+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
57+
58+
[homepage]: https://www.contributor-covenant.org
59+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

‎CONTRIBUTING.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Contributing to CZero Engine Python SDK
2+
3+
Thank you for your interest in contributing to the CZero Engine Python SDK! We welcome contributions from the community.
4+
5+
## 🚀 Getting Started
6+
7+
1. **Fork the Repository**
8+
```bash
9+
git clone https://github.com/czero/workflow-template.git
10+
cd workflow-template
11+
```
12+
13+
2. **Set Up Development Environment**
14+
```bash
15+
# Install UV package manager
16+
pip install uv
17+
18+
# Install dependencies
19+
uv pip install -e ".[dev]"
20+
```
21+
22+
3. **Verify Setup**
23+
```bash
24+
# Run tests
25+
uv run pytest
26+
27+
# Check code style
28+
uv run ruff check .
29+
```
30+
31+
## 📝 Development Workflow
32+
33+
### 1. Create a Feature Branch
34+
```bash
35+
git checkout -b feature/your-feature-name
36+
```
37+
38+
### 2. Make Your Changes
39+
- Write clean, readable code
40+
- Follow existing code patterns
41+
- Add type hints for all functions
42+
- Update documentation as needed
43+
44+
### 3. Test Your Changes
45+
```bash
46+
# Run all tests
47+
uv run pytest
48+
49+
# Run specific test
50+
uv run pytest tests/test_integration.py::test_your_feature
51+
52+
# Check coverage
53+
uv run pytest --cov=czero_engine --cov-report=html
54+
```
55+
56+
### 4. Submit Pull Request
57+
- Push your branch to your fork
58+
- Create a pull request with clear description
59+
- Link any related issues
60+
61+
## 🎯 Guidelines
62+
63+
### Code Style
64+
- Use Python 3.11+ features
65+
- Follow PEP 8 conventions
66+
- Maximum line length: 100 characters
67+
- Use descriptive variable names
68+
69+
### Testing
70+
- Write tests for new features
71+
- Maintain or improve code coverage
72+
- Test edge cases and error handling
73+
- Use async/await consistently
74+
75+
### Documentation
76+
- Update docstrings for new functions
77+
- Add examples for complex features
78+
- Keep README.md current
79+
- Document breaking changes
80+
81+
## 🏗️ Project Structure
82+
83+
```
84+
workflow-template/
85+
├── czero_engine/ # Main SDK package
86+
│ ├── client.py # API client
87+
│ ├── models.py # Pydantic models
88+
│ └── workflows/ # High-level workflows
89+
├── tests/ # Test suite
90+
├── examples/ # Usage examples
91+
└── docs/ # Additional documentation
92+
```
93+
94+
## 🧪 Testing Requirements
95+
96+
All contributions must:
97+
- Pass existing tests
98+
- Include tests for new features
99+
- Maintain 80%+ code coverage
100+
- Handle errors gracefully
101+
102+
## 📦 Submitting Changes
103+
104+
### Pull Request Checklist
105+
- [ ] Tests pass locally
106+
- [ ] Code follows style guidelines
107+
- [ ] Documentation is updated (see below)
108+
- [ ] Commit messages are clear
109+
- [ ] PR description explains changes
110+
111+
#### What "Documentation is updated" means:
112+
Update documentation when your changes affect:
113+
- **Docstrings**: Add/update function and class docstrings in your code
114+
- **README.md**: Update if you add new features, change SDK usage, or improve examples
115+
- **Examples**: Update or add example scripts if you introduce new functionality
116+
- **Type hints**: Ensure all new functions have proper type annotations
117+
- **CHANGELOG.md**: Add entry for breaking changes or major features (if file exists)
118+
119+
Examples:
120+
- Adding a new workflow? → Update README.md with usage example
121+
- New client method? → Add docstring with parameters and return type
122+
- Improved error handling? → Update relevant documentation
123+
- Fixed a common issue? → Consider adding to troubleshooting section
124+
125+
Note: The CZero Engine API is closed source and cannot be modified by external contributors. This SDK is a client library that interfaces with the existing API.
126+
127+
### Commit Message Format
128+
```
129+
type: brief description
130+
131+
Longer explanation if needed
132+
Fixes #issue_number
133+
```
134+
135+
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
136+
137+
## 🔧 Development Tips
138+
139+
### Running CZero Engine Locally
140+
1. Download CZero Engine from [czero.cc](https://czero.cc)
141+
2. Start the application
142+
3. Ensure API server is running on port 1421
143+
4. Load required models through the UI
144+
145+
### Debug Mode
146+
```python
147+
# Enable verbose logging
148+
client = CZeroEngineClient(verbose=True)
149+
150+
# Use environment variables
151+
CZERO_API_URL=http://localhost:1421
152+
CZERO_VERBOSE=true
153+
```
154+
155+
### Common Issues
156+
- **Connection refused**: Ensure CZero Engine is running
157+
- **Model not loaded**: Load models through the app UI
158+
- **Timeout errors**: Increase client timeout for LLM operations
159+
160+
## 🤝 Code of Conduct
161+
162+
### Our Standards
163+
- Be respectful and inclusive
164+
- Welcome newcomers
165+
- Accept constructive criticism
166+
- Focus on what's best for the community
167+
168+
### Unacceptable Behavior
169+
- Harassment or discrimination
170+
- Trolling or insulting comments
171+
- Public or private harassment
172+
- Publishing private information
173+
174+
## 📋 Issue Reporting
175+
176+
When reporting issues, include:
177+
1. Python version and OS
178+
2. CZero Engine version
179+
3. Steps to reproduce
180+
4. Error messages/logs
181+
5. Expected vs actual behavior
182+
183+
## 🎖️ Recognition
184+
185+
Contributors are recognized in:
186+
- GitHub contributors page
187+
- Release notes
188+
- Project documentation
189+
190+
## 📞 Getting Help
191+
192+
- 💬 [Discord Community](https://discord.gg/yjEUkUTEak)
193+
- 🐛 [Issue Tracker](https://github.com/czero/workflow-template/issues)
194+
- 📧 [Email](mailto:info@czero.cc)
195+
196+
## 📜 License
197+
198+
By contributing, you agree that your contributions will be licensed under the MIT License.
199+
200+
---
201+
202+
Thank you for contributing to CZero Engine! 🚀

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2025 CZero Engine
3+
Copyright (c) 2025 Fiefworks, inc.
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

0 commit comments

Comments
 (0)