Metadata-Version: 2.4
Name: clawed
Version: 0.9.5
Summary: Claw-ED — Your teaching files, your AI co-teacher. Upload curriculum materials, get a digital co-teacher that generates lessons in your voice.
Project-URL: Homepage, https://github.com/SirhanMacx/Claw-ED
Project-URL: Documentation, https://github.com/SirhanMacx/Claw-ED#readme
Project-URL: Issues, https://github.com/SirhanMacx/Claw-ED/issues
Author: Jon Maccarello & Claw-ED contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claw-ed,clawed,education,lesson-plans,teachers,teaching
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Requires-Python: >=3.10
Requires-Dist: anthropic<1.0,>=0.40.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>=3.1.0
Requires-Dist: json-repair>=0.30.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic<3.0,>=2.0.0
Requires-Dist: pymupdf>=1.23.0
Requires-Dist: python-docx>=1.0.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: python-pptx>=0.6.21
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: reportlab>=4.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: slowapi<1.0,>=0.1.9
Requires-Dist: sse-starlette>=1.6.0
Requires-Dist: typer<1.0,>=0.9.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: all
Requires-Dist: faster-whisper>=0.10.0; extra == 'all'
Requires-Dist: gunicorn>=21.0.0; extra == 'all'
Requires-Dist: keyring>=24.0.0; extra == 'all'
Requires-Dist: onnxruntime>=1.16.0; extra == 'all'
Requires-Dist: textual>=0.56.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: apscheduler<4.0,>=3.10.0; extra == 'dev'
Requires-Dist: faster-whisper>=0.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: google
Requires-Dist: google-api-python-client>=2.0.0; extra == 'google'
Requires-Dist: google-auth-oauthlib>=1.0.0; extra == 'google'
Provides-Extra: hosted
Requires-Dist: gunicorn>=21.0.0; extra == 'hosted'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'hosted'
Provides-Extra: keyring
Requires-Dist: keyring>=24.0.0; extra == 'keyring'
Provides-Extra: memory
Requires-Dist: onnxruntime>=1.16.0; extra == 'memory'
Provides-Extra: pdf
Requires-Dist: weasyprint>=60.0; extra == 'pdf'
Provides-Extra: tui
Requires-Dist: textual>=0.56.0; extra == 'tui'
Provides-Extra: voice
Requires-Dist: faster-whisper>=0.10.0; extra == 'voice'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">Claw-ED</h1>
  <p align="center"><strong>Your AI teaching partner.</strong></p>
  <p align="center">An agentic AI that learns your teaching style, generates lessons in your voice, and handles the work so you can focus on your students.</p>
</p>

<p align="center">
  <a href="https://pypi.org/project/clawed/"><img src="https://img.shields.io/pypi/v/clawed?color=blue" alt="PyPI"></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10+-blue" alt="Python 3.10+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License"></a>
  <a href="https://github.com/SirhanMacx/Claw-ED/stargazers"><img src="https://img.shields.io/github/stars/SirhanMacx/Claw-ED" alt="GitHub stars"></a>
</p>

<p align="center">
  <a href="#-getting-started">Quickstart</a> · <a href="FEATURES.md">Features</a> · <a href="ROADMAP.md">Roadmap</a> · <a href="CONTRIBUTING.md">Contributing</a>
</p>

---

## What is Claw-ED?

Claw-ED is an AI agent for teachers. Not a chatbot. Not a template library. An agent that knows your teaching style, your standards, your students — and acts on that knowledge.

```
You: "Prep my week"

Claw-ED:
  → Checks your curriculum map (8th grade Civics, Week 3: Bill of Rights)
  → Generates 5 differentiated lessons in your voice
  → Creates worksheets, assessments, and slides
  → Exports to PPTX, DOCX, or PDF
  → Uploads to your Google Drive
  → Asks: "Period 3 struggled with amendments last week. Want me to add a reteach?"
```

It learns from your existing lesson plans, aligns to your state's standards, and gets better every time you give feedback.

---

## How it works

```
Your lesson plans (PDFs, DOCX, PPTX, TXT)
        ↓
Claw-ED reads them and learns your teaching fingerprint:
  • Teaching style (inquiry-based, direct instruction, Socratic...)
  • Structural preferences (Do Nows, exit tickets, AIM questions...)
  • Vocabulary level and tone
  • Assessment approach
        ↓
You talk to it naturally — it decides what tools to use:
  • "Plan a 2-week unit on WWI for my 10th graders"
  • "Make a quiz on chapter 5"
  • "Export yesterday's lesson as slides"
  • "What standards haven't I covered yet?"
        ↓
Claw-ED acts — generates content, searches standards, exports files
        ↓
You teach. You give feedback. It improves.
```

### Real output

Generated for an 8th grade Social Studies class studying the American Revolution:

**Unit plan:**

```
Unit: "Liberty and Loyalty: The American Revolution"
Duration: 2 weeks (10 lessons)

Essential Questions:
  1. Was war inevitable?
  2. What defines freedom?
  3. How do ideas change the world?
  4. When is rebellion justified?
```

**Lesson 1 — Do Now (verbatim from generation):**

> Alright, friends, as you settle in, I want you to take out your notebook and answer this question on the board: 'What does freedom mean to you? Is there ever a time when following the rules is more important than being free?' Take 5 minutes to jot down your honest thoughts. There are no wrong answers here; I just want to hear your voice.

Every lesson includes differentiation, exit tickets, and homework — all in the teacher's voice.

---

## Getting Started

```bash
pip install clawed
clawed
```

That's it. Claw-ED walks you through setup in 30 seconds:
1. **Pick your AI provider** — we recommend Ollama Cloud ($20/month flat rate, unlimited lessons)
2. **Paste your API key** — get one from your provider's website
3. **Connect Telegram** (optional) — paste your bot token to use Claw-ED from your phone
4. **Start chatting** — the agent introduces itself and learns about you conversationally

### Other ways to use it

| Method | Command |
|--------|---------|
| **Terminal chat** | `clawed` or `clawed chat` |
| **Web dashboard** | `clawed serve` → open `http://localhost:8000` |
| **Full-screen TUI** | `pip install 'clawed[tui]'` → `clawed serve &` → `clawed tui` |
| **Telegram bot** | `clawed bot` (token saved during setup, or [setup guide](docs/BOT_SETUP.md)) |
| **Student bot** | Students join with class codes, ask questions in your voice |

---

## Architecture

Claw-ED is agent-first. Every natural-language message goes through an LLM that decides which tools to call. Deterministic operations (file ingestion, onboarding, button callbacks) bypass the agent for reliability.

```
Teacher's message (Telegram, CLI, TUI, Web)
        ↓
    Gateway
    ├── Control Plane (deterministic: files, callbacks, onboarding)
    └── Agent Loop (LLM decides → calls tools → returns result)
              ↓
        22 Tools
        generate_lesson · generate_unit · generate_materials
        generate_assessment · search_standards · export_document
        ingest_materials · configure_profile · request_approval
        search_lessons · curriculum_map · gap_analysis
        sub_packet · parent_comm · drive_upload · drive_list
        drive_organize · drive_create_slides · drive_create_doc
        drive_read · schedule_task
              ↓
    GatewayResponse → Teacher sees the result
```

See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full breakdown.

---

## What it can do

### Generation
- Unit plans, daily lessons, worksheets, assessments, rubrics — all in your voice
- IEP/504 accommodations and differentiation (struggling, advanced, ELL)
- Substitute teacher packets and parent communications
- PPTX slides with academic images, DOCX handouts, PDF exports

### Standards
- 50-state standards alignment (CCSS, NGSS, C3, state-specific frameworks)
- Curriculum gap analyzer — find what you haven't covered yet
- Standards search — look up specific standards by subject and grade

### Agent capabilities
- Agent-first gateway — LLM decides what tools to call, no hardcoded routing
- 22 typed tools auto-discovered from the tool registry
- Approval gates — agent asks before consequential actions
- 3-layer cognitive memory — identity, curriculum state, episodic recall
- Google Drive integration — upload, list, organize, native Slides/Docs, read
- Proactive scheduling — automated morning prep, weekly planning, feedback digests
- Custom teacher tools — define your own tools in YAML, no code needed
- Multi-step planner — "prepare my week" decomposes into sequential tool calls
- Autonomy progression — auto-approval offers when you consistently approve an action
- Closed feedback loop — ratings and feedback improve future generation
- Student insights — surfaces what students are confused about for reteaching
- Teacher preference learning — adapts to your editing patterns over time

### Surfaces
- Terminal chat, full-screen TUI, web dashboard, Telegram bot
- Student chatbot — students join with class codes, ask questions, get answers in your voice
- MCP server — expose tools to any AI agent
- REST API for custom integrations

### Coming next

| Version | What's coming |
|---------|--------------|
| **v0.9.0** *(current)* | Autonomy progression, closed feedback loop, student insights, preference learning, 22 tools |
| **v1.0.0** | District deployment with admin dashboard and SSO |

---

## Commands

| Command | What it does |
|---------|-------------|
| `clawed` | First run: setup. Returning: drops into chat with your agent |
| `clawed chat` | Terminal chat |
| `clawed tui` | Full-screen TUI chat (connects to running gateway) |
| `clawed serve` | Web server — dashboard, onboarding wizard, API |
| `clawed bot --token TOKEN` | Telegram bot |
| `clawed ingest <path>` | Learn from your lesson plans |
| `clawed unit "Topic" -g 8 -s "Subject"` | Generate a unit plan |
| `clawed lesson "Topic" -g 8 -s "Subject"` | Generate a single lesson |
| `clawed lesson "Topic" --format pptx` | Export as PowerPoint, Word, or PDF |
| `clawed standards list -g 8 -s math` | Browse your state's standards |
| `clawed gap-analyze -s "Math" -g 8` | Find curriculum gaps |
| `clawed demo` | See example output (no API key needed) |

Run `clawed --help` for the full list.

---

## Installation

```bash
pip install clawed                    # Everything you need
pip install 'clawed[tui]'             # + Full-screen terminal chat (Textual)
pip install 'clawed[voice]'           # + Voice note transcription
pip install 'clawed[all]'             # Everything

# Requires Python 3.10+
```

### Which AI provider?

The setup wizard asks you to pick a provider and paste your API key. That's it.

**We recommend [Ollama Cloud](https://ollama.com)** — $20/month Pro subscription, unlimited lessons, dozens of models. Default model: `minimax-m2.7:cloud`.

| Provider | Default model | Cost | Best for |
|----------|------------|------|----------|
| **Ollama Cloud** (recommended) | minimax-m2.7:cloud | $20/month flat | Daily use — unlimited lessons |
| **Anthropic** | Claude Sonnet 4.6 | ~$20+/lesson | Best output quality, expensive |
| **OpenAI** | GPT-5.4 | ~$20+/lesson | Best output quality, expensive |

Claude and GPT produce the best lesson output, but frontier model pricing is steep — a single lesson with differentiation and materials can cost $20 or more. Ollama Cloud lets you generate as much as you want for a fixed $20/month.

**Switch providers or models anytime:**

```bash
clawed config set-model ollama        # switch to Ollama Cloud
clawed config set-model anthropic     # switch to Claude
clawed config set-model openai        # switch to OpenAI
clawed setup --reset                  # re-run full setup
```

---

## Privacy & Compliance

- **Your files stay on your machine** unless you choose a cloud LLM provider
- **API keys stored in OS keychain** when `keyring` is installed, otherwise in `~/.eduagent/` with restrictive permissions
- **No telemetry, no data collection, no accounts**
- **Student bot transparency:** The student chatbot is clearly AI-powered. Students should know they are interacting with an AI assistant, not their teacher directly.
- **Not yet FERPA/COPPA certified.** Claw-ED does not currently have formal compliance certifications. Do not use it with personally identifiable student information (PII), IEP/504 documents containing real student names, or school-issued accounts until district-level compliance controls are implemented (planned for v1.0). Use it with your own lesson materials and generic/anonymized content.
- **Cloud LLM disclaimer:** When using cloud AI providers (Ollama Cloud, Anthropic, OpenAI), your lesson prompts are sent to their APIs. Review your provider's data handling policy. For maximum privacy, use a local Ollama installation.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Subject matter experts welcome — if you know how great lessons are structured in your subject, open a PR.

## License

MIT. Open source.

---

**Built by a teacher.** Claw-ED was created by **Mr. Mac** — 9 years teaching Social Studies in Long Island, NY. Not a startup's idea of what teachers need. A tool built by someone who writes lesson plans every week and got tired of starting from scratch.

<p align="center">
  <strong>If Claw-ED saves you time, <a href="https://github.com/SirhanMacx/Claw-ED/stargazers">star it on GitHub</a></strong> so other teachers can find it.
</p>
