Skip to content

Commit 4df6947

Browse files
author
GeneAI
committed
feat: Create production-ready PyPI package structure
Added comprehensive packaging infrastructure for publishing to PyPI: **New Files:** - pyproject.toml: Modern PEP 517/518 package configuration - Package name: "empathy" (PyPI standard lowercase) - Fair Source 0.9 license with LICENSE file reference - Optional dependencies: [llm], [memdocs], [full], [all] - Console scripts: "empathy" and "empathy-scan" - All package metadata (Smart-AI-Memory org) - MANIFEST.in: Controls which files are included in distribution - Includes docs, examples, configs, and tests - Excludes build artifacts, .env, .vscode, etc. - PUBLISHING.md: Complete guide for building and publishing - Step-by-step PyPI publishing instructions - TestPyPI testing workflow - GitHub Actions automation setup - Installation options reference **Updated Files:** - README.md: Quick Start now shows PyPI installation - pip install empathy[full] # Recommended - pip install empathy[llm] # LLM providers - pip install empathy[memdocs] # MemDocs integration - Development installation with -e .[dev] - requirements.txt: Updated header - Fair Source 0.9 (was Apache 2.0) - Smart-AI-Memory (was Deep Study AI, LLC) - setup.py → setup.py.legacy: Moved to legacy - pyproject.toml is now the source of truth - Kept for reference/compatibility **Package Structure:** Name: empathy (not empathy-framework) Version: 1.5.0 License: Fair Source 0.9 Python: >=3.10 **Optional Dependencies:** - [llm] - Anthropic + OpenAI clients - [memdocs] - MemDocs integration (when published) - [agents] - LangChain/LangGraph for workflows - [healthcare] - Healthcare plugin dependencies - [software] - Software plugin dependencies - [dev] - Development tools (pytest, black, ruff, etc.) - [full] - LLM + MemDocs + agents + plugins (recommended) - [all] - Everything including dev tools **Console Commands:** - empathy - Main CLI (was empathy-framework) - empathy-scan - Software security scanner **Distribution Files Built:** ✅ empathy-1.5.0.tar.gz (726K source distribution) ✅ empathy-1.5.0-py3-none-any.whl (206K wheel) **Next Steps:** 1. Test on TestPyPI: twine upload --repository testpypi dist/* 2. Verify installation works 3. Publish to PyPI: twine upload dist/* 4. Push git tag: git tag v1.5.0 && git push origin v1.5.0 See PUBLISHING.md for complete instructions.
1 parent e8bd055 commit 4df6947

File tree

6 files changed

+645
-14
lines changed

6 files changed

+645
-14
lines changed

‎MANIFEST.in‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Include documentation
2+
include README.md
3+
include LICENSE
4+
include CHANGELOG.md
5+
include CONTRIBUTING.md
6+
include SPONSORSHIP.md
7+
8+
# Include configuration files
9+
include pyproject.toml
10+
include setup.py
11+
include requirements.txt
12+
include .bandit
13+
include pytest.ini
14+
include .coveragerc
15+
16+
# Include all YAML/JSON configs
17+
recursive-include src *.yml *.yaml *.json
18+
recursive-include empathy_* *.yml *.yaml *.json
19+
recursive-include coach_wizards *.yml *.yaml *.json
20+
recursive-include wizards *.yml *.yaml *.json
21+
recursive-include agents *.yml *.yaml *.json
22+
23+
# Include documentation
24+
recursive-include docs *.md *.rst *.txt
25+
26+
# Include examples
27+
recursive-include examples *.py *.md *.yml *.yaml
28+
29+
# Include tests (for source distributions)
30+
recursive-include tests *.py
31+
32+
# Exclude unnecessary files
33+
global-exclude *.pyc
34+
global-exclude *.pyo
35+
global-exclude *.pyd
36+
global-exclude __pycache__
37+
global-exclude *.so
38+
global-exclude *.dylib
39+
global-exclude .DS_Store
40+
global-exclude .git*
41+
global-exclude .env
42+
global-exclude .vscode
43+
global-exclude .idea

‎PUBLISHING.md‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
# Publishing Guide for Empathy
2+
3+
This guide covers how to build and publish the Empathy package to PyPI.
4+
5+
## Prerequisites
6+
7+
1. **PyPI Account**: Create accounts on both:
8+
- [TestPyPI](https://test.pypi.org/account/register/) (for testing)
9+
- [PyPI](https://pypi.org/account/register/) (for production)
10+
11+
2. **API Tokens**: Create API tokens for both services:
12+
- TestPyPI: https://test.pypi.org/manage/account/token/
13+
- PyPI: https://pypi.org/manage/account/token/
14+
- Store tokens securely (they're only shown once!)
15+
16+
3. **Install Build Tools**:
17+
```bash
18+
pip install build twine
19+
```
20+
21+
## Building the Package
22+
23+
### 1. Update Version
24+
25+
Edit version in [`pyproject.toml`](pyproject.toml):
26+
```toml
27+
[project]
28+
version = "1.5.0" # Update this
29+
```
30+
31+
### 2. Clean Previous Builds
32+
33+
```bash
34+
rm -rf dist/ build/ *.egg-info
35+
```
36+
37+
### 3. Build Distribution Files
38+
39+
```bash
40+
python -m build
41+
```
42+
43+
This creates:
44+
- `dist/empathy-1.5.0.tar.gz` (source distribution)
45+
- `dist/empathy-1.5.0-py3-none-any.whl` (wheel distribution)
46+
47+
### 4. Verify Package Contents
48+
49+
```bash
50+
# Check what's in the wheel
51+
unzip -l dist/empathy-1.5.0-py3-none-any.whl
52+
53+
# Check what's in the source distribution
54+
tar -tzf dist/empathy-1.5.0.tar.gz
55+
```
56+
57+
## Testing the Package
58+
59+
### 1. Upload to TestPyPI
60+
61+
```bash
62+
twine upload --repository testpypi dist/*
63+
```
64+
65+
When prompted:
66+
- Username: `__token__`
67+
- Password: Your TestPyPI API token (starts with `pypi-`)
68+
69+
### 2. Test Installation from TestPyPI
70+
71+
Create a fresh virtual environment and test:
72+
73+
```bash
74+
# Create test environment
75+
python -m venv test_env
76+
source test_env/bin/activate # On Windows: test_env\Scripts\activate
77+
78+
# Install from TestPyPI
79+
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ empathy[full]
80+
81+
# Test import
82+
python -c "from empathy_os import EmpathyOS; print('Success!')"
83+
84+
# Deactivate and clean up
85+
deactivate
86+
rm -rf test_env
87+
```
88+
89+
**Note**: The `--extra-index-url` is needed because TestPyPI doesn't have all dependencies.
90+
91+
## Publishing to Production PyPI
92+
93+
### 1. Final Checks
94+
95+
- [ ] All tests passing (`pytest`)
96+
- [ ] Coverage meets requirements (`pytest --cov`)
97+
- [ ] Security scan clean (`bandit -r src/`)
98+
- [ ] Pre-commit hooks passing (`pre-commit run --all-files`)
99+
- [ ] Version number updated in [`pyproject.toml`](pyproject.toml)
100+
- [ ] [`CHANGELOG.md`](CHANGELOG.md) updated with release notes
101+
- [ ] Documentation up to date
102+
103+
### 2. Upload to PyPI
104+
105+
```bash
106+
twine upload dist/*
107+
```
108+
109+
When prompted:
110+
- Username: `__token__`
111+
- Password: Your PyPI API token (starts with `pypi-`)
112+
113+
### 3. Verify on PyPI
114+
115+
Visit: https://pypi.org/project/empathy/
116+
117+
### 4. Test Production Installation
118+
119+
```bash
120+
# Create fresh environment
121+
python -m venv verify_env
122+
source verify_env/bin/activate
123+
124+
# Install from PyPI
125+
pip install empathy[full]
126+
127+
# Verify
128+
python -c "from empathy_os import EmpathyOS; print('Production package works!')"
129+
130+
# Clean up
131+
deactivate
132+
rm -rf verify_env
133+
```
134+
135+
### 5. Create Git Tag and GitHub Release
136+
137+
```bash
138+
# Create and push tag
139+
git tag -a v1.5.0 -m "Release version 1.5.0"
140+
git push origin v1.5.0
141+
```
142+
143+
The GitHub Actions workflow ([`.github/workflows/release.yml`](.github/workflows/release.yml)) will automatically:
144+
- Create a GitHub Release
145+
- Upload distribution files
146+
- Publish to PyPI (if `PYPI_API_TOKEN` secret is configured)
147+
148+
## GitHub Actions Automation
149+
150+
### Setting up PyPI Token in GitHub
151+
152+
1. Go to: `https://github.com/Smart-AI-Memory/empathy/settings/secrets/actions`
153+
2. Click "New repository secret"
154+
3. Name: `PYPI_API_TOKEN`
155+
4. Value: Your PyPI API token
156+
5. Click "Add secret"
157+
158+
### Automated Release Process
159+
160+
Once the token is configured, releases are automatic:
161+
162+
```bash
163+
# Just push a version tag
164+
git tag v1.5.0
165+
git push origin v1.5.0
166+
```
167+
168+
GitHub Actions will:
169+
1. Build the package
170+
2. Run tests
171+
3. Create GitHub Release
172+
4. Publish to PyPI
173+
174+
## Installation Options Reference
175+
176+
After publishing, users can install with:
177+
178+
```bash
179+
# Minimal installation
180+
pip install empathy
181+
182+
# Transformative stack (recommended)
183+
pip install empathy[full]
184+
185+
# Specific components
186+
pip install empathy[llm] # LLM providers
187+
pip install empathy[memdocs] # MemDocs integration
188+
pip install empathy[agents] # LangChain agents
189+
pip install empathy[all] # Everything + dev tools
190+
191+
# Development
192+
git clone https://github.com/Smart-AI-Memory/empathy.git
193+
cd empathy
194+
pip install -e .[dev]
195+
```
196+
197+
## Package Structure
198+
199+
```
200+
empathy/
201+
├── pyproject.toml # Modern package configuration
202+
├── setup.py # Legacy support (optional)
203+
├── MANIFEST.in # Include/exclude files
204+
├── README.md # PyPI project description
205+
├── LICENSE # Fair Source 0.9
206+
├── src/
207+
│ └── empathy_os/ # Main package
208+
├── empathy_llm_toolkit/ # LLM integrations
209+
├── empathy_software_plugin/
210+
├── empathy_healthcare_plugin/
211+
├── coach_wizards/
212+
├── wizards/
213+
├── agents/
214+
└── tests/
215+
```
216+
217+
## Troubleshooting
218+
219+
### "File already exists" error on PyPI
220+
221+
You cannot re-upload the same version. Either:
222+
- Increment version number
223+
- Delete the release from PyPI (not recommended)
224+
225+
### Missing dependencies in wheel
226+
227+
Check [`MANIFEST.in`](MANIFEST.in) includes all necessary files.
228+
229+
### Import errors after installation
230+
231+
Verify package structure in [`pyproject.toml`](pyproject.toml):
232+
```toml
233+
[tool.setuptools]
234+
packages = ["empathy_os", "empathy_llm_toolkit", ...]
235+
```
236+
237+
## Version Numbering
238+
239+
Follow [Semantic Versioning](https://semver.org/):
240+
241+
- **1.0.0** → **1.0.1**: Bug fixes (PATCH)
242+
- **1.0.0** → **1.1.0**: New features, backward compatible (MINOR)
243+
- **1.0.0** → **2.0.0**: Breaking changes (MAJOR)
244+
245+
## Resources
246+
247+
- [Python Packaging Guide](https://packaging.python.org/)
248+
- [PyPI Help](https://pypi.org/help/)
249+
- [Twine Documentation](https://twine.readthedocs.io/)
250+
- [setuptools Documentation](https://setuptools.pypa.io/)
251+
252+
## License
253+
254+
When publishing, ensure the Fair Source License 0.9 is properly included in the distribution package. The license automatically converts to Apache 2.0 on January 1, 2029.
255+
256+
---
257+
258+
**Need help?** Contact [[email protected]](mailto:[email protected])

‎README.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,23 @@
1414
## Quick Start
1515

1616
```bash
17-
# Clone and install from source (PyPI package coming soon)
17+
# Install core framework
18+
pip install empathy
19+
20+
# Install with Claude Code + MemDocs transformative stack (recommended)
21+
pip install empathy[full]
22+
23+
# Or install specific components:
24+
pip install empathy[llm] # LLM providers (Anthropic, OpenAI)
25+
pip install empathy[memdocs] # MemDocs integration
26+
pip install empathy[all] # Everything including dev tools
27+
```
28+
29+
**Development installation:**
30+
```bash
1831
git clone https://github.com/Smart-AI-Memory/empathy.git
1932
cd empathy
20-
pip install -r requirements.txt
33+
pip install -e .[dev]
2134
```
2235

2336
```python

0 commit comments

Comments
 (0)