Tcm

Name: Tcm
Rating: 3.5 (1 reviews)
Author: durgasathwik

By durgasathwik 👁 31 views ▲ 0 votes

OpenClaw plugin suite: IDrive e2 index + NotebookLM bridge + MCQ generation pipeline

GitHub

Install

npm install
pnpm

README

# TCM — OpenClaw plugin suite

Turn an IDrive e2 S3 bucket of study material into MCQ quiz CSVs via NotebookLM.

Three OpenClaw plugins working together. No deployment scaffolding — you bring the OpenClaw gateway, this repo brings the brains.

## What it does

- **`tcm-idrive`** — Indexes your S3 bucket into a local SQLite store. Exposes `openclaw tcm idrive sync/ls/tree/find/get/presign` plus an `idrive_find` MCP tool for agents. Also writes optional per-folder summary markdown into OpenClaw's memory directory so `memory_search` can find your study material by topic.
- **`tcm-notebooklm`** — Wraps the [`nlm`](https://pypi.org/project/notebooklm-mcp-cli/) CLI. Exposes `openclaw tcm nlm status/create/add/ask/list`.
- **`tcm-quiz`** — Orchestrator. Resolves a folder/file from the index, downloads each source, uploads to a NotebookLM notebook (reusing per topic — new sources are appended, never re-uploaded), asks for MCQs, writes a CSV, uploads to a separate output bucket, prints a presigned download URL. Exposes `openclaw tcm quiz generate/list/show/download/forget` and an `mcq_status` MCP tool.

## Bucket model

One bucket per subject. Typical setup:

```
s3://maths/    s3://biology/    s3://english/    s3://physics/
s3://chemistry/ s3://hindi/     s3://social/     s3://telugu/
s3://tcm-mcqs/   ← output bucket where generated CSVs land
```

Each subject bucket holds nested folders of source files (PDFs, notes, slides). Source specs everywhere use `<bucket>/<keyOrPrefix>` syntax — e.g. `biology/Genetics` means the `Genetics/` prefix in the `biology` bucket. Just `biology` means everything in that bucket.

## End-to-end user flow

```
# 1. one-time
openclaw tcm setup                          # interactive: keys, region, bucket list, nlm path
openclaw tcm idrive sync                    # scan every subject bucket

# 2. anytime
openclaw tcm quiz generate "biology/Genetics" --count 30 --difficulty medium
# → CSV in s3://tcm-mcqs/mcq/<jobId>-biology-genetics.csv
# → presigned download URL printed (24h TTL by default)

# Other examples:
openclaw tcm quiz generate biology --count 20         # whole subject
openclaw tcm quiz generate maths/algebra --count 15   # one subfolder
```

If you're invoking this from a Telegram-fronted agent (or any other agent connected to the gateway): the agent shells out to the same CLI commands and reads the final JSON line for the result. The 30 MCQs never enter the agent's context — only the receipt does.

## Install

Each plugin is a separate npm package in this monorepo. To install into an existing OpenClaw gateway:

```bash
# clone
git clone https://github.com/durgasathwik/tcm.git
cd tcm
pnpm install
pnpm -r exec tsc -p tsconfig.json   # builds dist/

# tell openclaw about the local packages
openclaw plugins install ./packages/tcm-idrive
openclaw plugins install ./packages/tcm-notebooklm
openclaw plugins install ./packages/tcm-quiz
```

OpenClaw can also install plugins directly from a git URL — see [`docs/INSTALL.md`](./docs/INSTALL.md) for the exact recipes.

After install, run the setup wizard:

```bash
openclaw tcm setup                            # interactive — terminal users
```

Or non-interactively (e.g. driven from a chat agent shelling out):

```bash
openclaw tcm setup --yes \
  --endpoint https://s3.ap-northeast-1.idrivee2.com --region ap-northeast-1 \
  --access-key "$AK" --secret-key "$SK" \
  --subject-buckets auto --output-bucket tcm-mcqs --apply-config --json
```

Either form writes `~/.tcm/.env` (mode 0600), verifies subject buckets, checks `nlm`, and either prints or auto-applies the `openclaw.json` snippet. See [`docs/INSTALL.md`](./docs/INSTALL.md) for the full flag set and JSON-receipt schema.

## CLI cheatsheet

| Command | What it does |
| --- | --- |
| `openclaw tcm setup` | Interactive credential setup |
| `openclaw tcm idrive sync [--prefix <bucket>[/<path>]]` | Scan all subject buckets → SQLite + memory summaries |
| `openclaw tcm idrive ls` | List subject buckets |
| `openclaw tcm idrive ls <bucket>[/<path>]` | List folder contents inside a bucket |
| `openclaw tcm idrive tree [bucket] [--depth N]` | Tree view across all buckets or one |
| `openclaw tcm idrive find <query> [--bucket N]` | Fuzzy search filenames across buckets |
| `openclaw tcm idrive get <bucket>/<key> --out <path>` | Download one object |
| `openclaw tcm idrive presign <bucket>/<key>` | Print a presigned download URL |
| `openclaw tcm nlm status` | NotebookLM auth check |
| `openclaw tcm nlm create <title>` | Create a notebook, print its ID |
| `openclaw tcm nlm add <nb-id> --file <path>` | Add a source |
| `openclaw tcm nlm ask <nb-id> "<q>" [--json]` | Query a notebook |
| `openclaw tcm quiz generate <source> [--count N] [--difficulty L]` | Generate MCQ CSV |
| `openclaw tcm quiz list [--status done\|running\|error]` | Recent jobs |
| `openclaw tcm quiz show <jobId>` | Full job record (JSON) |
| `openclaw tcm quiz download <jobId>` | Presigned download URL for CSV |
| `openclaw tcm quiz forget <topic>` | Clear notebook-reuse mapping for a topic |

## How notebook reuse works

`tcm-quiz` maintains `~/.tcm/notebook-map.json` mapping `<source-path>` → `{ notebookId, sources: { <key>: { etag } } }`. On each `generate`:

1. Look up the topic. If a notebook already exists for it, reuse the same notebook.
2. Diff the resolved source files against what's tracked in the notebook by S3 ETag.
3. Only newly-added or content-changed files get downloaded and uploaded to NotebookLM. Already-tracked sources are left in place.
4. Run the MCQ query against the notebook. Update the map's `lastUsedAt`.

Result: subsequent quizzes on the same topic are fast and your NotebookLM accumulates sources rather than spawning duplicates. If you want a fresh notebook for a topic, run `openclaw tcm quiz forget "<topic>"`.

## State

| Where | What |
| --- | --- |
| `~/.tcm/index.db` | SQLite file/folder index (rebuildable from a fresh `sync`) |
| `~/.tcm/jobs/<id>.json` | One file per quiz job |
| `~/.tcm/notebook-map.json` | Topic → notebook ID mapping |
| `~/.tcm/.env` | Secrets (mode 0600) written by `setup` |
| `s3://tcm-study/` | Your study materials (canonical) |
| `s3://tcm-mcqs/` | Generated CSVs (canonical) |

## Development

```bash
pnpm install
pnpm -r exec tsc -p tsconfig.json
pnpm -r exec vitest run
```

Tests live in each package under `src/__tests__/`. Network-heavy paths (S3, nlm) are tested at the integration boundary only — unit tests cover parsers, schemas, the SQLite store, and the notebook map.

## License

MIT — see [`LICENSE`](./LICENSE).

integration