Skip to content

Commit 9435353

Browse files
abrichrclaude
abrichr
and
claude
committed
docs: add legacy freeze documentation and migration notice
Document the decision to freeze the legacy monolithic OpenAdapt codebase at version 0.46.0 and direct users to the new modular meta-package architecture. - Add docs/LEGACY_FREEZE.md with full migration guide - Add prominent notice at top of README.md pointing to new packages - List all new modular packages (openadapt-ml, openadapt-capture, etc.) - Provide import path migration examples - Document benefits of the new architecture No legacy code has been deleted - this is documentation only. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent df97457 commit 9435353

2 files changed

Lines changed: 245 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,28 @@
1+
> ## Important Notice: New Modular Architecture Available
2+
>
3+
> **This repository contains the legacy monolithic OpenAdapt codebase (v0.46.0), which is now frozen.**
4+
>
5+
> Active development has moved to a new **modular meta-package architecture** with better maintainability and cleaner separation of concerns.
6+
>
7+
> **New packages:**
8+
> | Package | Description |
9+
> |---------|-------------|
10+
> | `openadapt` | Meta-package with unified CLI (v1.0.0+) |
11+
> | `openadapt-ml` | ML engine, training, inference |
12+
> | `openadapt-capture` | Event recording and storage |
13+
> | `openadapt-evals` | Benchmark evaluation |
14+
> | `openadapt-viewer` | HTML visualization |
15+
> | `openadapt-grounding` | UI element localization |
16+
> | `openadapt-retrieval` | Demo retrieval |
17+
>
18+
> **Quick start:** `pip install openadapt[all]`
19+
>
20+
> **Migration guide:** See [docs/LEGACY_FREEZE.md](docs/LEGACY_FREEZE.md) for migration instructions.
21+
>
22+
> **Legacy users:** This codebase remains available. Install with `pip install openadapt==0.46.0`
23+
24+
---
25+
126
[Join us on Discord](https://discord.gg/yF527cQbDG)
227

328
[Read our Architecture document](https://github.com/OpenAdaptAI/OpenAdapt/wiki/OpenAdapt-Architecture-(draft))

‎docs/LEGACY_FREEZE.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# Legacy OpenAdapt Codebase Freeze
2+
3+
**Date**: January 2026
4+
**Status**: Legacy Codebase Frozen
5+
**Last Version**: v0.46.0
6+
7+
---
8+
9+
## Decision Summary
10+
11+
The monolithic OpenAdapt codebase in this repository has been **frozen** as of version 0.46.0. Active development has moved to a new **modular meta-package architecture** that provides better maintainability, faster iteration, and cleaner separation of concerns.
12+
13+
**This codebase remains available for:**
14+
- Reference and historical purposes
15+
- Existing users who need to maintain current installations
16+
- Migration planning and compatibility testing
17+
18+
**No new features will be added to this codebase.**
19+
20+
---
21+
22+
## Last Known Working Version
23+
24+
| Property | Value |
25+
|----------|-------|
26+
| **Version** | 0.46.0 |
27+
| **PyPI Package** | `openadapt==0.46.0` |
28+
| **Python Support** | 3.10 - 3.11 |
29+
| **Release Date** | February 2025 |
30+
| **Repository** | https://github.com/OpenAdaptAI/OpenAdapt |
31+
32+
**To install the legacy version:**
33+
```bash
34+
pip install openadapt==0.46.0
35+
```
36+
37+
**Or clone and install from this repository:**
38+
```bash
39+
git clone https://github.com/OpenAdaptAI/OpenAdapt.git
40+
cd OpenAdapt
41+
pip install poetry
42+
poetry install
43+
```
44+
45+
---
46+
47+
## New Modular Architecture
48+
49+
The new OpenAdapt ecosystem is split into focused, independently-versioned packages:
50+
51+
| Package | Description | Installation |
52+
|---------|-------------|--------------|
53+
| **openadapt** | Meta-package (unified CLI + re-exports) | `pip install openadapt` (v1.0.0+) |
54+
| **openadapt-ml** | ML engine, training, inference | `pip install openadapt-ml` |
55+
| **openadapt-capture** | Event recording and storage | `pip install openadapt-capture` |
56+
| **openadapt-evals** | Benchmark evaluation infrastructure | `pip install openadapt-evals` |
57+
| **openadapt-viewer** | HTML visualization components | `pip install openadapt-viewer` |
58+
| **openadapt-grounding** | UI element localization (optional) | `pip install openadapt-grounding` |
59+
| **openadapt-retrieval** | Multimodal demo retrieval (optional) | `pip install openadapt-retrieval` |
60+
61+
**Quick start with new packages:**
62+
```bash
63+
# Install everything
64+
pip install openadapt[all]
65+
66+
# Or install what you need
67+
pip install openadapt-ml openadapt-capture
68+
```
69+
70+
---
71+
72+
## Migration Guide
73+
74+
### For Library Users
75+
76+
**Before (Legacy v0.46.0):**
77+
```python
78+
from openadapt.record import record
79+
from openadapt.replay import replay
80+
from openadapt.models import Recording, ActionEvent
81+
from openadapt.strategies.visual import VisualReplayStrategy
82+
```
83+
84+
**After (New Architecture v1.0.0+):**
85+
```python
86+
# Recording
87+
from openadapt import CaptureSession, Recorder
88+
89+
# ML (training and inference)
90+
from openadapt import AgentPolicy
91+
from openadapt_ml.training import train_supervised
92+
93+
# Evaluation
94+
from openadapt import ApiAgent, evaluate_agent_on_benchmark
95+
96+
# Viewer
97+
from openadapt import PageBuilder
98+
```
99+
100+
### For Application Users (Desktop Tray App)
101+
102+
The legacy PySide6-based tray application is **not included** in the new packages. Options:
103+
104+
1. **Continue using legacy**: Pin to `openadapt==0.46.0`
105+
2. **Use CLI**: The new `openadapt` CLI provides all core functionality
106+
3. **Future**: A new cross-platform application is planned
107+
108+
### For Contributors
109+
110+
**Legacy development setup:**
111+
```bash
112+
git clone https://github.com/OpenAdaptAI/OpenAdapt
113+
cd OpenAdapt
114+
poetry install
115+
```
116+
117+
**New development setup:**
118+
```bash
119+
# Clone specific sub-package
120+
git clone https://github.com/OpenAdaptAI/openadapt-ml
121+
cd openadapt-ml
122+
uv sync # or pip install -e ".[dev]"
123+
```
124+
125+
### Data Migration
126+
127+
**Database format changed:**
128+
129+
| Legacy | New |
130+
|--------|-----|
131+
| SQLite database (`openadapt.db`) | JSON/Parquet captures |
132+
| `Recording` SQLAlchemy model | `Capture` Pydantic model |
133+
| `ActionEvent` with foreign keys | `ActionEvent` standalone |
134+
135+
A migration script will be provided to convert legacy recordings to the new format.
136+
137+
### CLI Changes
138+
139+
| Legacy CLI | New CLI |
140+
|------------|---------|
141+
| `python -m openadapt.record "task"` | `openadapt capture start --name "task"` |
142+
| `python -m openadapt.replay visual` | `openadapt replay --strategy visual` |
143+
| `python -m openadapt.visualize` | `openadapt capture view <name>` |
144+
145+
### Python Version
146+
147+
| Legacy | New |
148+
|--------|-----|
149+
| Python 3.10 - 3.11 | Python 3.12+ |
150+
151+
---
152+
153+
## Benefits of the New Architecture
154+
155+
### 1. Faster Development Cycles
156+
- Each package has independent CI/CD
157+
- Changes to `openadapt-ml` don't require rebuilding `openadapt-capture`
158+
- Smaller test suites per package = faster feedback
159+
160+
### 2. Cleaner Dependencies
161+
- Legacy had 80+ direct dependencies
162+
- New packages have minimal, focused dependencies
163+
- Optional heavy dependencies (grounding, retrieval) are truly optional
164+
165+
### 3. Better Versioning
166+
- Semantic versioning per package
167+
- Breaking changes in ML don't force capture upgrades
168+
- Easier to pin specific versions
169+
170+
### 4. Modern Python Support
171+
- Python 3.12+ with modern typing
172+
- Native async/await support
173+
- Better performance
174+
175+
### 5. Easier Contribution
176+
- Contributors can focus on one package
177+
- Clear ownership and responsibility
178+
- Smaller codebases to understand
179+
180+
### 6. Optional Features
181+
- Install only what you need
182+
- `openadapt[grounding]` for UI grounding
183+
- `openadapt[retrieval]` for demo retrieval
184+
- `openadapt[all]` for everything
185+
186+
---
187+
188+
## Frequently Asked Questions
189+
190+
### Q: Will the legacy package be removed from PyPI?
191+
**A:** No. `openadapt==0.46.0` will remain available indefinitely. New versions (1.0.0+) will be the meta-package.
192+
193+
### Q: Can I still file issues against the legacy codebase?
194+
**A:** Critical security fixes will be considered. New features should be requested against the new packages.
195+
196+
### Q: What about my existing recordings?
197+
**A:** A migration tool will be provided. Contact us on Discord if you need help migrating.
198+
199+
### Q: Is the desktop tray app still supported?
200+
**A:** The legacy tray app works with `openadapt==0.46.0`. A new cross-platform app is planned for the new architecture.
201+
202+
---
203+
204+
## Support
205+
206+
- **Discord**: https://discord.gg/yF527cQbDG
207+
- **GitHub Issues**: https://github.com/OpenAdaptAI/OpenAdapt/issues (legacy)
208+
- **New Packages Issues**: See individual package repositories
209+
210+
---
211+
212+
## Related Documents
213+
214+
- [Legacy Transition Plan](https://github.com/OpenAdaptAI/openadapt-evals/blob/main/docs/research/legacy-transition-plan.md)
215+
- [New Architecture Design](https://github.com/OpenAdaptAI/openadapt-ml/blob/main/docs/new_openadapt_architecture.md)
216+
- [OpenAdapt Meta-Package](https://github.com/OpenAdaptAI/openadapt) (coming soon)
217+
218+
---
219+
220+
*This document was created as part of the OpenAdapt modular architecture transition. The legacy codebase served the community well from 2023-2025 and its patterns inform the new design.*

0 commit comments

Comments
 (0)