yoker-assistant

A personal assistant that communicates by email, built on yoker-as-SDK.

Python owns the email loop (poll, fetch, reply, archive) and calls Yoker as a library for the reasoning half. The package is also a Yoker plugin provider (dual-mode): it exposes its own tools via __YOKER_MANIFEST__ for any Yoker consumer to load.

This is one of two Yoker 1.0 showcase packages. Its sister project yoker-writing-assistant demonstrates yoker-as-runtime; this one demonstrates yoker-as-SDK: the Python process owns the loop and imports Yoker as a library.

What You’ll Find Here

• Tutorial — the build story, end-to-end. Why this package exists, the two halves, the seams, the handoff contract, the bounded tool set, the persistent session, the dual-mode architecture, and the git demo beat.

• Quickstart — a worked example showing the assistant in action, from first email to PERSONAL.md commit.

• Architecture — seam-by-seam reference for the loop, the SDK integration, and the email gateway.

• Design Decisions — what was kept, reworked, removed, and added when building for the Yoker SDK context.

• Security — the trust model, reply-safety boundary, and the manifest review process.

• Configuration — the full ~/.yoker.toml, .env, and PERSONAL.md reference.

• API — the public API surface.

• Changelog — release history.

Contents

• Installation
  • Prerequisites
  • Install the package
  • Backend prerequisite
  • Plugin registration — automatic
  • Email account (.env)
  • Verify the install
• Quickstart
  • Run one iteration
  • The PERSONAL.md bootstrap flow
  • A worked example: teaching the assistant a preference
  • Graceful shutdown
  • Next
• Tutorial — How yoker-assistant Was Built
  • 1. Why this exists
  • 2. The two halves
  • 3. The seams
  • 4. The handoff contract
  • 5. The bounded tool set
  • 6. Design decisions — what was kept, reworked, and dropped
  • 7. The persistent-session architecture
  • 8. The custom md→html tool story
  • 9. Dual-mode architecture
  • 10. The git commit/push demo beat
  • 11. Recipient safety
  • 12. Out of scope (first pass)
• Architecture
  • The two halves
  • The loop module
  • The yoker SDK seam
  • The simple-email-gw seam
  • The handoff contract
  • The bounded tool set
  • The persistent-session architecture
  • Dual-mode architecture
  • The custom md→html tool
  • Loop behavior
  • Entry point
• Design Decisions
  • The agent definition
  • The tools list
  • What moved to Python
  • What was reworked
  • What was dropped
  • Summary
• Security
  • Trust blast radius
  • Recipient whitelist — the primary reply-safety boundary
  • ~/.yoker.toml and .env are NEVER committed
  • The manifest-addition review process
  • Publishing guards
  • Deliberate non-additions
• Configuration
  • Email account — .env
  • yoker runtime — ~/.yoker.toml
  • Assistant personalization — PERSONAL.md
  • Loop parameters
• API Reference
  • yoker_assistant.loop.run(once=False)
  • yoker_assistant.loop.build_message(email_message)
  • yoker_assistant.tools.md_to_html(markdown)
  • yoker_assistant.__YOKER_MANIFEST__
  • CLI
  • Configuration
• Changelog
  • Unreleased
  • 0.1.2 — 2025-07-18
  • 0.1.1 — 2025-07-18
  • 0.1.0 — 2026-07-23

Indices and Tables

• Index

• Module Index

• Search Page

• Index

• Module Index

• Search Page