Metadata-Version: 2.5
Name: clawed
Version: 9.18.2026.1
Summary: Your AI co-teacher. Generate lessons, games, slides, and assessments from your terminal. Learns your teaching voice, aligns to your state standards, and works with any LLM provider.
Project-URL: Homepage, https://sirhanmacx.github.io/Claw-ED
Project-URL: Documentation, https://github.com/SirhanMacx/Claw-ED#readme
Project-URL: Repository, https://github.com/SirhanMacx/Claw-ED
Project-URL: Bug Tracker, https://github.com/SirhanMacx/Claw-ED/issues
Project-URL: Changelog, https://github.com/SirhanMacx/Claw-ED/blob/main/CHANGELOG.md
Project-URL: PyPI, https://pypi.org/project/clawed/
Author: Jon Maccarello & Claw-ED contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,ai-for-teachers,animation,claw-ed,clawed,curriculum,edtech,education,educational-videos,hermes-agent,k12,lesson-plan-generator,lesson-planner,lesson-planning,lesson-plans,manim,open-source-education,pedagogy,teacher-tools,teachers,teaching,teaching-assistant
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Education :: Computer Aided Instruction (CAI)
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: anthropic<1.0,>=0.39.0
Requires-Dist: apscheduler<4.0,>=3.10.0
Requires-Dist: fastapi<1.0,>=0.110.0
Requires-Dist: httpx<1.0,>=0.25.0
Requires-Dist: jinja2<4.0,>=3.1.0
Requires-Dist: json-repair<1.0,>=0.30.0
Requires-Dist: lxml<7.0,>=4.9.0
Requires-Dist: mcp<2.0,>=1.0.0
Requires-Dist: openai<2.0,>=1.50.0
Requires-Dist: pydantic<3.0,>=2.0.0
Requires-Dist: pypdf<7.0,>=6.10.2
Requires-Dist: python-docx<2.0,>=1.0.0
Requires-Dist: python-multipart<1.0,>=0.0.6
Requires-Dist: python-pptx<2.0,>=0.6.21
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: reportlab!=4.4.10,<5.0,>=4.0.0
Requires-Dist: rich<14.0,>=13.0.0
Requires-Dist: sse-starlette<3.0,>=1.6.0
Requires-Dist: typer<1.0,>=0.9.0
Requires-Dist: urllib3<3.0,>=2.5.0
Requires-Dist: uvicorn[standard]<1.0,>=0.27.0
Provides-Extra: all
Requires-Dist: faster-whisper<2.0,>=0.10.0; extra == 'all'
Requires-Dist: gtts<3.0,>=2.5.0; extra == 'all'
Requires-Dist: keyring<26.0,>=24.0.0; extra == 'all'
Requires-Dist: onnxruntime<2.0,>=1.16.0; extra == 'all'
Requires-Dist: qrcode[pil]<9.0,>=7.0; extra == 'all'
Requires-Dist: textual<2.0,>=0.56.0; extra == 'all'
Requires-Dist: uvicorn[standard]<1.0,>=0.27.0; extra == 'all'
Provides-Extra: animations
Requires-Dist: av<18.0,>=12.0; extra == 'animations'
Requires-Dist: manim<1.0,>=0.18.0; extra == 'animations'
Provides-Extra: browser
Requires-Dist: playwright<2.0,>=1.40.0; extra == 'browser'
Provides-Extra: dev
Requires-Dist: apscheduler<4.0,>=3.10.0; extra == 'dev'
Requires-Dist: build<2.0,>=1.0.0; extra == 'dev'
Requires-Dist: faster-whisper<2.0,>=0.10.0; extra == 'dev'
Requires-Dist: mypy<2.0,>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0,>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0,>=4.0; extra == 'dev'
Requires-Dist: pytest<10.0,>=9.0.3; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.1.0; extra == 'dev'
Requires-Dist: types-python-dateutil<3.0,>=2.9.0; extra == 'dev'
Requires-Dist: types-pytz<2027.0.0,>=2025.0.0; extra == 'dev'
Requires-Dist: types-pyyaml<7.0,>=6.0.0; extra == 'dev'
Requires-Dist: types-qrcode<9.0,>=8.2.0; extra == 'dev'
Requires-Dist: types-reportlab<5.0,>=4.4.0; extra == 'dev'
Provides-Extra: formats
Requires-Dist: striprtf<1.0,>=0.0.26; extra == 'formats'
Requires-Dist: xlrd<3.0,>=2.0.0; extra == 'formats'
Provides-Extra: google
Requires-Dist: google-api-python-client<3.0,>=2.0.0; extra == 'google'
Requires-Dist: google-auth-oauthlib<2.0,>=1.0.0; extra == 'google'
Provides-Extra: keyring
Requires-Dist: keyring<26.0,>=24.0.0; extra == 'keyring'
Provides-Extra: memory
Requires-Dist: onnxruntime<2.0,>=1.16.0; extra == 'memory'
Provides-Extra: pdf
Requires-Dist: weasyprint<70.0,>=60.0; extra == 'pdf'
Provides-Extra: pdf-rich
Requires-Dist: pymupdf<2.0,>=1.23.0; extra == 'pdf-rich'
Provides-Extra: qr
Requires-Dist: qrcode[pil]<9.0,>=7.0; extra == 'qr'
Provides-Extra: tts
Requires-Dist: gtts<3.0,>=2.5.0; extra == 'tts'
Provides-Extra: tui
Requires-Dist: textual<2.0,>=0.56.0; extra == 'tui'
Provides-Extra: voice
Requires-Dist: faster-whisper<2.0,>=0.10.0; extra == 'voice'
Description-Content-Type: text/markdown

# Claw-ED

> Your curriculum. Your teaching voice. Lessons you can review and edit.

Claw-ED is a local-first AI teaching assistant. Start with your existing lesson plans, slides, and assessments; use them to draft new lessons, student materials, and presentations. You choose the model and review the result before using or sharing it.

**Current release: v9.18.2026.1 · Beta · Python 3.11+**

[Install](#setup) · [Website](https://sirhanmacx.github.io/Claw-ED/) · [Release notes](CHANGELOG.md) · [Security and privacy](SECURITY.md) · [Report an issue](https://github.com/SirhanMacx/Claw-ED/issues)

## Start with one lesson

1. **Bring your materials.** Import a folder of PDF, DOCX, PPTX, TXT, or Markdown files. Claw-ED extracts text, indexes material for retrieval, and builds a teaching-style profile.
2. **Give it a concrete task.** Specify the topic, class, learning objective, and materials you need. Existing material and your saved profile can inform the draft.
3. **Review the outputs.** Check source accuracy, answer keys, pacing, accessibility, and layout. Edit the DOCX and PPTX files in your usual tools.
4. **Choose what to deliver.** Keep files locally or use configured integrations. Student access and external publication need deliberate setup.

The lesson bundle tool creates a teacher DOCX, student DOCX, and PPTX slides. Optional extensions can add differentiated materials, games, and other formats. The actual result depends on the request, model, installed extras, and successful exports; a fixed file count is not guaranteed.

## Setup

Use Python 3.11 or newer in a virtual environment:

```bash
python -m venv .venv
# macOS / Linux:
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade clawed
clawed setup
```

Choose a provider and configure access in the setup wizard. Then try the Python commands:

```bash
clawed ingest ./my-lessons/
clawed lesson "Causes of the French Revolution" -g 10 -s "Global History"
clawed serve                         # local dashboard and API
clawed --version
```

Run `clawed` for the owned Python interface; Node.js and Bun are no longer required. `clawed -p "request"` uses the same gateway and tool policy. For command-specific options, use `clawed <command> --help`.

[Getting started](docs/GETTING_STARTED.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)

## What is available today

| Area | What it provides | What to check |
| --- | --- | --- |
| Curriculum ingestion | Text extraction, search, teaching-style profiles, and image extraction | Retrieval may miss or shorten relevant material; inspect the sources used |
| Lesson production | Structured lesson content, teacher/student documents, and slides | Factual accuracy, source attribution, answer keys, and classroom fit |
| Quality checks | Section, source-text, differentiation, and assessment checks with bounded repair attempts | These are automated checks, not proof that a lesson is ready to teach |
| Dashboard and API | Local lesson views, teacher chat, exports, and student embed snippets | Teacher authentication and correct share-link setup |
| Integrations | Telegram, Google Drive, Classroom-related tools, and MCP | Provider credentials, permissions, and destination readback |
| Experimental features | Games, simulations, scheduling, live classroom sessions, and student-facing tools | Feature-specific limitations; some session state does not survive restarts |

The release is intended for a single teacher per instance. It is not a multi-tenant school platform. Student-facing features remain experimental within Claw-ED.

## What v9.18.2026.1 changes

- Remove the bundled third-party terminal runtime; all entry points use Python.
- Keep your chosen model, isolate concurrent tool requests, and support GPT-6 Astra and Claude Fable 5.1 request formats.
- Add a Jobs page and CLI cancel, recover, and resume commands with saved generation phases.
- Preserve multilingual text and full source excerpts; include a source manifest that flags quotations needing review.
- Refresh local and budget model recommendations against current provider catalogs.

For a recoverable bundle, use the dashboard's **Jobs** page or:

```bash
clawed queue submit bundle --topic "River civilizations" --grade 9 --subject History
clawed queue worker
# In another terminal, when needed:
clawed queue cancel JOB_ID
clawed queue recover
clawed queue resume JOB_ID
```

The worker must be running to process jobs. Completed matching phases survive restarts; external publishing and arbitrary chat sessions are not automatically resumed. Existing configuration and teaching data are preserved. See the [changelog](CHANGELOG.md).

## Models and privacy

Provider adapters support Anthropic, OpenAI, Google Gemini, Ollama, and OpenRouter. Model support and tool behavior vary by provider and task. API pricing, quotas, and model availability are set by the provider; Claw-ED does not include model usage.

**Start here:** [dated model recommendations and setup](docs/CHOOSING_A_MODEL.md). Try Qwen 3.5 9B locally, GPT-OSS 20B or Gemma 4 31B on OpenRouter for a budget trial, and explicitly select Astra or Fable for premium work. Recommendations are starting points, not measured classroom rankings.

Configuration and working data are stored locally under `~/.eduagent/` by default. **Local storage does not mean all processing stays on the device.** Hosted models receive the prompts and selected content needed for a request. Web search, image retrieval, Telegram, Google integrations, and package installation also contact their respective services when used.

For local inference, configure a locally running model and avoid cloud providers and network-dependent features. Review what you ingest and share; remove student identifiers where possible. The application is not a certification of compliance with school data policies.

Teacher web routes require authentication. The dashboard uses an HttpOnly session cookie with same-origin checks on changes; API clients can use a bearer token. Student embeds use lesson share tokens and separate conversation tokens. Keep the server local unless you have configured access controls for the intended audience.

Read [SECURITY.md](SECURITY.md) for the trust boundary and reporting process.

## Useful commands

```bash
clawed                                  # interactive assistant
clawed ingest ./my-lessons/              # import teaching materials
clawed lesson "Topic" -g 8 -s "History"  # draft a lesson
clawed unit "Topic" -g 9 -w 3            # draft a multi-week unit
clawed assess "Topic" --type crq         # draft an assessment
clawed kb query "question"               # search the curriculum wiki
clawed bot                              # Telegram interface
clawed serve                            # local dashboard and API
clawed drive auth                       # configure Google Drive access
clawed schedule list                    # inspect configured schedules
clawed mcp-server                       # expose tools to an MCP client
```

## Development

```bash
git clone https://github.com/SirhanMacx/Claw-ED.git
cd Claw-ED
python -m pip install -e ".[dev]"
ruff check .
mypy --strict clawed
pytest tests/
```

CI exercises Python 3.11 and 3.12, wheel installation, and Docker startup. Most tests use synthetic data or mocked model responses; passing CI does not establish teaching quality across live models. See the [architecture](docs/ARCHITECTURE.md) and [evaluation protocol](docs/EVALUATION.md).

Useful contributions include reproducible bugs, teacher-reviewed sample lessons, source-fidelity checks, and improvements to a complete import → draft → review → export workflow. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [roadmap](ROADMAP.md).

Claw-ED's original code is released under the [MIT license](LICENSE). Third-party components retain their own terms. The project is maintained by [MacxLabs](https://macxlabs.app/?src=github-claw-ed-readme); [supporting development](https://macxlabs.app/support/?src=github-claw-ed-readme) is optional.
