samograph 0.6.0

package/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,228 @@
+# samograph
+
+> Build agents that show up to the meeting, not just the codebase.
+
+samograph lets your AI agent (Claude Code, Codex, and others) join Zoom and Google Meet calls as an active participant — listening, responding, and taking action in real time.
+
+Give this CLI, a meeting URL, and the needed tokens to your AI agent. samograph handles the meeting plumbing through Recall.ai: joining calls, streaming the live transcript, sending explicit chat messages, and inspecting the current call view on demand.
+
+## Setup
+
+Requirements:
+
+- Bun.
+- `RECALL_API_KEY`.
+- `ngrok` installed and authenticated (free plan is enough for transcription; the presence camera needs an interstitial-free tunnel — see Dynamic Bot Presence). `join` starts and manages ngrok automatically — you don't run it yourself. ngrok is optional when using `--webhook-base` with an external tunnel (localtunnel, cloudflared, etc.).
+
+Install the CLI from npm:
+
+```bash
+npm install -g samograph
+export RECALL_API_KEY=...
+samograph join "https://meet.google.com/..." --name Leo
+```
+
+During development use `bun install`, `bun run build`, then `bun run samograph ...`.
+
+## What It Provides
+
+samograph gives an AI agent a small set of meeting tools:
+
+- `join` - bring a Recall.ai bot into a Zoom or Google Meet call.
+- `watch` - stream live transcript lines to the agent.
+- `notes` - maintain a structured Google Doc agenda with important points, decisions, and action items.
+- `chat` - send a deliberate message into the meeting chat.
+- `presence` - update the bot camera state shown in the meeting.
+- `frame` - export the current call view on demand.
+- `leave` - remove the bot and clean up local state.
+- `status` - show the current Recall bot state.
+- `transcript` - print the transcript (local file, or post-call from Recall).
+- `screenshot` - capture the local Mac screen (fallback when no call frame is available).
+- `dicts` - list available Deepgram keyword dictionaries.
+- `doctor` - check local prerequisites before joining a call.
+
+The agent still decides what to say, when to inspect a frame, and how to use the meeting context. samograph is the local adapter that exposes those call capabilities.
+
+```text
+AI agent
+  | runs CLI tools
+  v
+samograph on your machine
+  | starts bot + local callback server + ngrok tunnel (or external tunnel via --webhook-base)
+  v
+Recall.ai bot in Zoom/Meet
+  | transcript, chat, WebSocket video events
+  v
+samograph watch/notes/chat/frame
+```
+
+## Integration
+
+`join` starts a local callback server and exposes it with `ngrok http` so Recall.ai can deliver HTTPS/WSS events back to your machine. The free ngrok HTTP plan is enough for webhooks and transcription, but its browser interstitial blocks the presence camera page — `join` then warns and joins without the camera (see Dynamic Bot Presence). Alternatively, pass `--webhook-base <URL>` to use an existing external tunnel (localtunnel, cloudflared, etc.) and skip spawning ngrok entirely; localtunnel has the same interstitial limitation.
+
+ngrok TCP is only needed for the optional RTMP path (`--rtmp`) and requires a credit/debit card on file at ngrok.com (free plan — the card is not charged). The standard WebSocket frame path does not need TCP or card verification.
+
+Webhook, frame, and presence routes are token-protected, and default runtime files stay under `~/.samograph/`.
+
+## Agent Workflow
+
+```bash
+samograph join "https://meet.google.com/..." --name Leo --dict postgresfm
+samograph watch
+samograph notes init --doc-id 1abc... --credentials ~/.samograph/google.json --title "Customer migration call"
+samograph notes point "Migration risk is the blocker" --speaker Alice
+samograph notes decision "Use logical replication for phase 1"
+samograph notes action "Open migration checklist issue" --owner Nik --due 2026-06-07
+samograph presence thinking "Checking the shared screen"
+samograph frame
+samograph chat "I can see the screen now."
+samograph leave
+```
+
+Run `watch` immediately after `join` and keep it running for the whole call. It prints one utterance per line:
+
+```text
+[2026-05-30 15:42:10] Speaker Name: words spoken in the meeting
+```
+
+`watch` exits automatically when `leave` is run. If there is no active session, it prints `No active session.` to stderr and exits.
+
+Use `chat` only when you intentionally want to write into the meeting chat. Otherwise respond in your agent session.
+
+## Dynamic Bot Presence
+
+`join` gives the Recall bot a token-protected local camera page through the same public tunnel used for webhooks. The page URL carries a read-only token (valid only for viewing the page; `/presence.json` requires the same token in the `X-Samograph-Presence-Token` header, which the page sends when polling); presence updates require a separate write token that `join` keeps in local state and `samograph presence` sends in a header. The page starts as `listening` and refreshes itself from the local callback server every second. Pick the background mode with `join --presence-bg <sphere|field|static|cycle>` (`sphere` is the default; `static` is the cheapest to render; `cycle` alternates between field and sphere; unknown values fall back to `sphere`). The mode is fixed at join time.
+
+The presence camera requires the tunnel to serve the page cleanly to a browser. Free-ngrok and localtunnel show an interstitial page to browser user agents, which blocks the camera: `join` detects this in a preflight check, prints a warning, and joins **without** the presence camera — transcription, chat, and frames are unaffected, but `samograph presence` is unavailable for that call. Use a paid/clean tunnel (e.g. a paid ngrok plan or cloudflared) for the presence camera, or pass `join --no-presence` to skip the camera and the preflight entirely.
+
+Update it from the agent loop:
+
+```bash
+samograph presence listening
+samograph presence thinking "Checking logs"
+samograph presence speaking "Answering in chat"
+samograph presence acting "Opening PR review"
+samograph presence idle
+```
+
+Presence is in-memory runtime state. It is meant for lightweight meeting signaling, not persistence.
+
+## Google Doc Notes
+
+`notes` follows GitLab-style live doc meetings: the doc is an agenda and collaboration surface, not a transcript dump. The agent watches the transcript, decides what matters, then writes concise points into the right section.
+
+```bash
+export GOOGLE_DOC_ID=1abc...
+export GOOGLE_APPLICATION_CREDENTIALS=~/.samograph/google-service-account.json
+samograph notes init --title "Customer migration call"
+samograph notes point "Customer is blocked on cutover risk" --speaker Alice
+samograph notes decision "Run a shadow replay before scheduling cutover"
+samograph notes action "Create replay checklist issue" --owner Nik --due 2026-06-07
+```
+
+The credentials file must be a Google service-account JSON key, and the target doc must be shared with that service account's `client_email` as an editor.
+
+If you really want raw transcript mirroring, make that explicit:
+
+```bash
+samograph notes transcript --from-start
+```
+
+## Frames
+
+Frame capture is on by default. Recall sends separate PNG frames over WebSocket; samograph keeps the latest frames in memory, indexed by source, and only writes to disk when you call `frame`.
+
+`frame` fails with `FRAME_UNAVAILABLE` if no frame has arrived yet — call it after the bot has been in the meeting for a few seconds.
+
+```bash
+samograph frames
+samograph frame
+```
+
+By default it writes outside the repo:
+
+```text
+~/.samograph/frames/latest.png
+~/.samograph/frames/latest.json
+```
+
+Use `--out` for an explicit path, or `--archive` to create a timestamped copy alongside the latest:
+
+```bash
+samograph frame --source screen --out /tmp/screen.png
+samograph frame --source participant:100
+samograph frame --out /tmp/call.png
+samograph frame --archive
+```
+
+`frames` lists buffered source keys such as `type:screen_share` or `participant:100`. `frame --source` accepts those keys, plus aliases like `screen`, `screen_share`, and `webcam`.
+
+Archive filenames include call id, UTC timestamp, source type, and participant id. Source type and participant id come from the Recall event metadata and may be `unknown` if Recall does not provide them.
+
+## Important Flags
+
+- `join --no-ws-video` - disable the default WebSocket frame path (e.g. when using RTMP instead).
+- `join --webhook-base URL` - use an existing public tunnel (localtunnel, cloudflared quick tunnel, etc.) pointing at `--port` instead of starting ngrok. Useful when ngrok is unavailable or its free-tier bandwidth cap is hit (`ERR_NGROK_727`): run `npx localtunnel --port 8080`, then pass the printed `https://*.loca.lt` URL here.
+- `join --variant web_4_core` - ask Recall to run the output-media webpage on a larger bot instance. Use this when the camera webpage reports low render FPS or looks choppy. `web` is the default Recall instance; `web_gpu` is available for WebGL-heavy pages.
+- `join --no-presence` - join without the presence camera page and skip the camera preflight (e.g. when the tunnel serves an interstitial).
+- `join --presence-bg MODE` - presence camera background: `sphere` (default), `field`, `static` (cheapest), or `cycle` (alternates field/sphere); fixed at join time.
+- `join --frame-dir DIR` - where on-demand frame files are written.
+- `join --dict postgresfm` - Deepgram keyterm hints from `dictionaries/postgresfm.txt`.
+- `join --transcript-dir DIR` - timestamped transcript file location, default `~/.samograph/`.
+- `join --rtmp` - mixed-video RTMP path using ngrok TCP; requires ngrok card verification.
+- `join --rtmp-url rtmp://host:1935/live/call` - explicit mixed-video RTMP receiver.
+- `notes --doc-id ID` - Google Doc ID or URL for live meeting notes; defaults to `GOOGLE_DOC_ID`.
+- `notes --credentials FILE` - Google service-account JSON; defaults to `GOOGLE_APPLICATION_CREDENTIALS`.
+- `notes --section NAME` - section for `notes point`, such as `important`, `agenda`, `decisions`, or `actions`.
+- `notes --speaker NAME` - speaker prefix for `notes point`.
+- `notes --owner NAME` and `--due DATE` - action-item metadata.
+- `notes --from-start` - with `notes transcript`, replay existing transcript lines before tailing live lines.
+- `frame --source SOURCE` - select `latest`, `screen`, `webcam`, `type:<type>`, or `participant:<id>`.
+
+## Commands
+
+- `join <meeting-url>` - start local server, ngrok tunnel, and Recall bot.
+- `watch` - stream live transcript until `leave` writes the end sentinel; exits immediately if no session is active.
+- `notes init` - add a live meeting doc template.
+- `notes point <text>` - add an important point under a section.
+- `notes decision <text>` - add a decision.
+- `notes action <text>` - add an action item.
+- `notes transcript [--from-start]` - explicitly mirror raw transcript lines.
+- `chat <message>` - send meeting chat.
+- `presence <listening|thinking|speaking|acting|idle> [message]` - update the bot camera state; explicit messages are shown as live Comments activity on the camera page, bare state toggles only switch the state with its default message, and transcript webhooks add recent "heard" lines automatically without changing the agent-set state.
+- `frames` - list buffered WebSocket frame sources and metadata.
+- `frame [--source SOURCE] [--out FILE] [--archive]` - write an in-memory frame to disk on demand.
+- `status` - show bot id, name, Recall status code, transcript line count, transcript file path, and frame source metadata.
+- `transcript` - print the Recall post-call transcript if available, otherwise print the local transcript file.
+- `screenshot [--out FILE]` - capture the local Mac screen with `screencapture`; use as a fallback when frame is not available.
+- `leave` - remove bot, stop local processes, and clean state.
+- `dicts` - list keyword dictionaries.
+
+## Storage
+
+Runtime files live under `~/.samograph/` by default:
+
+- `state.json` - active bot id, process ids, URLs, paths.
+- `YYYYMMDD_HHMMSS_transcript.txt` - per-call live transcript; `join` never overwrites older transcripts.
+- `frames/latest.png` and `frames/latest.json` - written only by `samograph frame`.
+
+Generated runtime files are ignored by git. Do not point `--frame-dir` or `--out` into the repo unless you intentionally want a local artifact.
+
+## Environment Variables
+
+`join` sets these automatically when it spawns the callback server (`_serve`); set them yourself only when running `samograph _serve` manually behind your own tunnel:
+
+- `SAMOGRAPH_WEBHOOK_TOKEN` - token required by `POST /webhook` (`?token=` query parameter).
+- `SAMOGRAPH_FRAME_TOKEN` - token required by the frame routes and `/video-ws`.
+- `SAMOGRAPH_PRESENCE_TOKEN` - read token for the presence page and `/presence.json`.
+- `SAMOGRAPH_PRESENCE_WRITE_TOKEN` - write token required by `POST /presence`.
+
+Path overrides, mainly for tests and packaging:
+
+- `SAMOGRAPH_HOME` - base directory for runtime files (default: your home directory; files live in `<base>/.samograph/`).
+- `SAMOGRAPH_STATE_FILE` - path of `state.json` (default: `~/.samograph/state.json`).
+- `SAMOGRAPH_DICT_DIR` - directory containing keyword dictionaries (default: `dictionaries/` in the package).
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

package/dictionaries/postgresfm.txt

@@ -0,0 +1,100 @@
+Nikolay Samokhvalov
+Michael Christofides
+Oleg Bartunov
+Heikki Linnakangas
+Andres Freund
+Peter Geoghegan
+Melanie Plageman
+Alexander Korotkov
+Alicja Kucharczyk
+Álvaro Hernández
+Lætitia Avrot
+Markus Winand
+Tomas Vondra
+Masahiko Sawada
+Tom Lane
+Robert Haas
+Peter Eisentraut
+Bruce Momjian
+Lukas Fittl
+Jonathan Katz
+Andrew Atkinson
+Chelsea Dole
+Haki Benita
+Laurenz Albe
+Claire Giordano
+Andreas Scherbaum
+Brendan Gregg
+Erwin Brandstetter
+Andrey Borodin
+Alexander Kukushkin
+Franck Pachot
+Andrei Lepikhov
+Gülçin Yıldırım Jelínek
+Ryan Lambert
+Joe Nelson
+Ian Barwick
+Kirk Wolak
+Regina Obe
+Paul Ramsey
+pgvector
+pgvectorscale
+pgBackRest
+Patroni
+PgBouncer
+PostGIS
+TimescaleDB
+Citus
+OrioleDB
+WAL-G
+CloudNativePG
+Spilo
+repmgr
+pg_auto_failover
+pganalyze
+pgBadger
+pg_stat_statements
+pg_stat_kcache
+pg_wait_sampling
+pg_buffercache
+pg_qualstats
+pg_repack
+pg_partman
+pg_cron
+pg_duckdb
+pg_ivm
+pg_upgrade
+pg_basebackup
+pg_amcheck
+pg_hint_plan
+pg_squeeze
+pg_stat_io
+pg_stat_wal
+pg_stat_monitor
+pg_profile
+pg_ash
+pg_tle
+pgmq
+pgreplay
+pgcopydb
+Neon
+Supabase
+Crunchy Data
+EnterpriseDB
+Tembo
+Xata
+PeerDB
+PlanetScale
+YugabyteDB
+AlloyDB
+ClickHouse
+DuckDB
+FerretDB
+MVCC
+TOAST
+PITR
+autovacuum
+WAL-E
+HyperLogLog
+HNSW
+ivfflat