Metadata-Version: 2.4
Name: mantrin
Version: 0.2.0
Summary: A personal chief of staff you talk to.
License: # Functional Source License, Version 1.1, ALv2 Future License
        
        ## Abbreviation
        
        FSL-1.1-ALv2
        
        ## Notice
        
        Copyright 2026 Saksham Jain
        
        ## Terms and Conditions
        
        ### Licensor ("We")
        
        The party offering the Software under these Terms and Conditions.
        
        ### The Software
        
        The "Software" is each version of the software that we make available under
        these Terms and Conditions, as indicated by our inclusion of these Terms and
        Conditions with the Software.
        
        ### License Grant
        
        Subject to your compliance with this License Grant and the Patents,
        Redistribution and Trademark clauses below, we hereby grant you the right to
        use, copy, modify, create derivative works, publicly perform, publicly display
        and redistribute the Software for any Permitted Purpose identified below.
        
        ### Permitted Purpose
        
        A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
        means making the Software available to others in a commercial product or
        service that:
        
        1. substitutes for the Software;
        
        2. substitutes for any other product or service we offer using the Software
           that exists as of the date we make the Software available; or
        
        3. offers the same or substantially similar functionality as the Software.
        
        Permitted Purposes specifically include using the Software:
        
        1. for your internal use and access;
        
        2. for non-commercial education;
        
        3. for non-commercial research; and
        
        4. in connection with professional services that you provide to a licensee
           using the Software in accordance with these Terms and Conditions.
        
        ### Patents
        
        To the extent your use for a Permitted Purpose would necessarily infringe our
        patents, the license grant above includes a license under our patents. If you
        make a claim against any party that the Software infringes or contributes to
        the infringement of any patent, then your patent license to the Software ends
        immediately.
        
        ### Redistribution
        
        The Terms and Conditions apply to all copies, modifications and derivatives of
        the Software.
        
        If you redistribute any copies, modifications or derivatives of the Software,
        you must include a copy of or a link to these Terms and Conditions and not
        remove any copyright notices provided in or with the Software.
        
        ### Disclaimer
        
        THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
        PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
        
        IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
        SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
        EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
        
        ### Trademarks
        
        Except for displaying the License Details and identifying us as the origin of
        the Software, you have no right under these Terms and Conditions to use our
        trademarks, trade names, service marks or product names.
        
        ## Grant of Future License
        
        We hereby irrevocably grant you an additional license to use the Software under
        the Apache License, Version 2.0 that is effective on the second anniversary of
        the date we make the Software available. On or after that date, you may use the
        Software under the Apache License, Version 2.0, in which case the following
        will apply:
        
        Licensed under the Apache License, Version 2.0 (the "License"); you may not use
        this file except in compliance with the License.
        
        You may obtain a copy of the License at
        
        http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software distributed
        under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
        CONDITIONS OF ANY KIND, either express or implied. See the License for the
        specific language governing permissions and limitations under the License.
        
Project-URL: Homepage, https://tryjarvis.in
Project-URL: Source, https://github.com/sailingsam/tryjarvis
Project-URL: Issues, https://github.com/sailingsam/tryjarvis/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: anthropic>=0.117
Requires-Dist: fastembed>=0.3
Requires-Dist: ddgs>=9.0
Requires-Dist: mcp>=1.0
Requires-Dist: tweepy>=4.16
Provides-Extra: voice
Requires-Dist: webrtcvad-wheels>=2.0; extra == "voice"
Requires-Dist: numpy>=1.24; extra == "voice"
Requires-Dist: openwakeword>=0.4; extra == "voice"
Requires-Dist: miniaudio>=1.60; extra == "voice"
Requires-Dist: websockets>=12; extra == "voice"
Provides-Extra: whisper
Requires-Dist: faster-whisper>=1.0; extra == "whisper"
Provides-Extra: piper
Requires-Dist: piper-tts>=1.6; extra == "piper"
Provides-Extra: all
Requires-Dist: mantrin[piper,voice,whisper]; extra == "all"
Dynamic: license-file

# Mantrin

**Everyone deserves a chief of staff — your personal Jarvis.**

Mantrin (you'll also see it called Jarvis — that's the name it answers to, and
the name of the package inside) is a personal chief of staff you talk to. It
remembers your people, your promises and your plans across every conversation,
and then acts on them.

Not a recorder and not a chat window. You say something once; it holds onto it
and does something about it.

> **Status: beta.** It runs my day, every day — but it's young: Linux only for
> now, version 0.x, and things change without ceremony. If you're the kind of
> person who enjoys software at this stage, welcome; if you need boring and
> settled, check back in a few releases.

## What's here

```
jarvis/
  core/memory.py       # the moat — durable facts with provenance. Not rented.
  core/brain.py        # understanding: reply, then decide what was worth learning
  audio.py             # mic, endpointing, playback — shared by every voice provider
  wake.py              # the wake word, running locally
  daemon.py            # the always-on process: holds the mic and the connections
  providers/llm.py     # rented intelligence (Claude) behind one interface
  providers/stt.py     # rented ears — local Whisper, OpenAI, Grok, or your own app
  providers/tts.py     # rented voice — local Piper, OpenAI, Grok
  providers/voice_registry.py   # the table of what you can pick, and what it needs
  tools/               # real actions: web, X, and any MCP server
  io/                  # the skin: voice or text, same brain either way
```

Everything replaceable sits behind an interface — the language model, the ears,
the voice, the memory store. What we own outright is the memory and the
understanding built on it.

## Install

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install "mantrin[voice]"
export ANTHROPIC_API_KEY=...
```

`[voice]` is the microphone layer. The heavy local providers install only if
you pick them: `mantrin setup` offers to fetch what your choices need, or grab
everything up front with `pip install "mantrin[all]"`. Working from a checkout
instead: `pip install -e ".[all]"` — see [CONTRIBUTING.md](CONTRIBUTING.md).

## Talk to it

```bash
mantrin setup      # choose whose ears and voice; save any keys
mantrin            # then just say "hey jarvis"
```

The default stack is free and entirely local — Whisper for hearing, Piper for
speaking, openWakeWord for the wake word. Nothing you say leaves the machine
until you choose a hosted provider.

There is no button and no time limit: it works out that you stopped talking by
listening. Interrupt it mid-sentence and it stops, like a person would. After it
answers it keeps listening for a few seconds, so a back-and-forth doesn't need
the wake word every time.

### Push-to-talk

```bash
mantrin set-key    # press the key you want; hold it to talk
```

Or there *is* a button, if you want one: hold your chosen key (any key — a
Lenovo star key, F10, whatever your keyboard has) and Mantrin listens; release
it and the answer comes. The release is the endpoint — no wake word, no
waiting out your pauses, and a press always interrupts a reply.

Three trigger modes (pick during `set-key`, or from the tray): wake word, talk
key, or both. In key-only mode the microphone device simply does not exist
between presses — your OS's mic light burning is exactly the time Mantrin
could hear anything.

Reading the keyboard needs your user in the `input` group (`set-key` offers
to add you; one logout applies it). Honest note: that permission can see every
key, so [`jarvis/hotkey.py`](jarvis/hotkey.py) stays one short, verifiable
file that matches a single keycode and ignores the rest.

### Type instead

```bash
mantrin --text        # keyboard in, text out
mantrin --dictate     # dictate with your own app, spoken reply
```

`--dictate` is for Wispr Flow's app, superwhisper, Willow and the rest. They own
the microphone and type into whatever has focus, so there is nothing to
integrate with — Mantrin reads the line and answers out loud.

### Swap providers

```bash
mantrin --stt grok --tts openai
mantrin --timings     # where each turn's time actually went
```

Settings live in `~/.config/mantrin/config.json` (mode 0600, it holds keys).
Anything in the environment wins over what is saved there.

Adding a provider is one class with one method, plus a line in
`providers/voice_registry.py`.

## See what it knows

```bash
mantrin memory        # every fact, and where it came from
mantrin commitments   # open loops it is tracking
mantrin brief         # a short daily brief
```

Memory is SQLite (`data/jarvis.db` in a checkout, `~/.local/share/mantrin/` when installed) — open it with `sqlite3` and you can read
everything it knows about you. Delete the file to give it amnesia.

## Integrations

WhatsApp, Gmail, Calendar, Spotify, GitHub, Notion, Home Assistant, X — and
anything with an MCP server — plug into the same tool registry.

```bash
mantrin connect            # list them, with live status
mantrin connect spotify    # guided: opens the key page, takes the key, verifies
```

Under the hood each is a block in `mcp.json` plus a key in the environment; a
block whose key isn't set yet just waits. [docs/integrations.md](docs/integrations.md)
has the by-hand steps for all of them.

Full docs, including a walkthrough of every command, live at
[docs.tryjarvis.in](https://docs.tryjarvis.in).

## The daemon

`mantrin` starts a background daemon on first run and then talks to it. The
daemon is where Mantrin actually lives: it holds the microphone and keeps
integrations like WhatsApp connected, so messages are still captured when you are
not in a session and there is no terminal to keep open.

Only one process may hold those connections — two would mean two WhatsApp clients
on one set of credentials — which is why voice runs there rather than in the CLI.

```bash
mantrin daemon        # run it in the foreground to watch it
mantrin --no-voice    # don't hold the microphone
```

### Run at every login

```bash
mantrin install
```

On Linux this installs a systemd user service and puts a `mantrin` command on
your PATH: Mantrin starts when you log in, restarts if it crashes, and there is
no terminal to keep open. From then on the commands are ones a person can
remember — `mantrin status`, `mantrin logs`, `mantrin restart`, `mantrin stop`,
`mantrin uninstall`.

It also puts a status icon in the top bar (`mantrin tray`, auto-started at
login): green means listening for the wake word, blue means mid-conversation,
yellow starting, red something's wrong. The menu holds a **Mute microphone**
hard mute — the mic device is released (your OS's mic light goes out) and even
the wake word is ignored, while the brain and connections keep working. Once a
talk key is set (`mantrin set-key`), a **Listen for** switch picks between
wake word, talk key, or both.

## Contributing

Issues and PRs welcome — [CONTRIBUTING.md](CONTRIBUTING.md) has the setup, the
rules that matter (start with the Human PA Test), and how changes are reviewed.
The label [good first issue](https://github.com/sailingsam/tryjarvis/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
marks self-contained starting points. Big roadmap features (proactivity,
streaming voice) are being built by the maintainer — open an issue to discuss
before starting anything large.

## License

[FSL-1.1-ALv2](LICENSE.md) — use it, change it, run it for yourself or inside
your company, all free. The one thing you can't do is take this code and sell
it as your own product or hosted service. Every release becomes plain
Apache 2.0 two years after it ships.

## Not there yet

Proactivity — it answers when spoken to, and does not yet start conversations
itself. Reminders and anything on a schedule need a real scheduler, not a
language model. Auto-reply to messages waits on always-on being solid first.
Google and Slack need your sign-in. Streaming transcription is worth adding only
if `--timings` says it would help.
