Metadata-Version: 2.4
Name: magi-ai-assistant
Version: 0.2.0
Summary: magi — an assistant-core engine: a lead routing to a specialist team, with memory, knowledge, and tools.
Project-URL: Homepage, https://github.com/carneirofc/magi-ai-assistant
Project-URL: Repository, https://github.com/carneirofc/magi-ai-assistant
Project-URL: Documentation, https://github.com/carneirofc/magi-ai-assistant/tree/master/docs
Project-URL: Changelog, https://github.com/carneirofc/magi-ai-assistant/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/carneirofc/magi-ai-assistant/issues
Author-email: Cláudio Carneiro <claudiofcarneiro@gmail.com>
Maintainer-email: Cláudio Carneiro <claudiofcarneiro@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,agno,ai,assistant,chatbot,discord,llm,memory,multi-agent,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: agno>=2.6.11
Requires-Dist: anthropic>=0.105.2
Requires-Dist: ddgs>=9.14.4
Requires-Dist: discord-py>=2.4.0
Requires-Dist: docker>=7.1.0
Requires-Dist: fastapi>=0.136.3
Requires-Dist: httpx>=0.28.0
Requires-Dist: litellm>=1.87.0
Requires-Dist: ollama>=0.6.2
Requires-Dist: openai>=2.40.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: sqlalchemy>=2.0.50
Requires-Dist: uvicorn[standard]>=0.48.0
Provides-Extra: desktop
Requires-Dist: pyside6>=6.8.0; extra == 'desktop'
Provides-Extra: git
Requires-Dist: gitpython>=3.1.40; extra == 'git'
Provides-Extra: mcp
Requires-Dist: mcp>=1.9.0; extra == 'mcp'
Provides-Extra: s3
Requires-Dist: boto3>=1.35.0; extra == 's3'
Provides-Extra: semantic
Requires-Dist: qdrant-client>=1.12.0; extra == 'semantic'
Description-Content-Type: text/markdown

# magi

<p align="center">
  <img src="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/imgs/magi.png" alt="MAGI logo" width="200">
</p>

<p align="center">
  <a href="https://pypi.org/project/magi-ai-assistant/"><img src="https://img.shields.io/pypi/v/magi-ai-assistant?logo=pypi&logoColor=white&label=PyPI" alt="PyPI version"></a>
  <a href="https://pypi.org/project/magi-ai-assistant/"><img src="https://img.shields.io/pypi/pyversions/magi-ai-assistant?logo=python&logoColor=white" alt="Python versions"></a>
  <a href="https://github.com/carneirofc/magi-ai-assistant/pkgs/npm/magi-web"><img src="https://img.shields.io/badge/npm-%40carneirofc%2Fmagi--web-cb3837?logo=npm&logoColor=white" alt="npm package @carneirofc/magi-web"></a>
  <a href="https://github.com/carneirofc/magi-ai-assistant/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
</p>

Personal multi-channel AI assistant on the [Agno](https://www.agno.com/) framework.
One shared agent brain, many channel adapters. Model-agnostic — local
llama.cpp `llama-server` by default (direct, or through the LiteLLM proxy);
Claude via the proxy; Ollama kept as a dormant fallback.

> **The name.** *MAGI* is the supercomputer at the heart of NERV in *Neon Genesis
> Evangelion* — three linked units (Melchior, Balthasar, Casper) that reason as
> one and reach decisions by majority vote. The nod fits: one shared brain backed
> by a roster of specialized members, speaking through many channels.

## Features

magi is the **reusable core of a personal AI assistant** — not one bot, but the
engine several bots share.

- **One shared brain, many channels.** A Discord bot, an HTTP API, an
  OpenAI-compatible shim, an embeddable desktop SDK, and a native desktop shell
  all drive the *same* assembled stack — only the transport differs.
- **Deliberate memory.** The assistant's durable knowledge of a user lives in
  inspectable files written *on purpose* by a post-turn curator — never silently
  auto-extracted. Recent turns, evicted-but-unsummarized turns, freshly-learned
  facts, and past episodes are all assembled into each run's context.
- **Bot identity.** A global, operator-set profile — display name, description,
  and profile picture — the assistant presents as itself: injected into every run
  so the model both *knows* its name and *can show* its picture on request.
- **Knowledge corpus (RAG).** A shared, read-only document corpus the assistant
  searches on demand — and optionally auto-injects the top hits for each message
  straight into context. Distinct from per-user memory.
- **Byte archive.** A durable file/image store the model uses as memory for
  bytes: stash a file, recall it later by reference. Local filesystem or any
  S3-compatible backend.
- **Admin dashboard.** A web UI to inspect and edit *everything* the assistant
  remembers — users, facts, sessions, knowledge, persona, and identity.
- **Model-agnostic.** Local `llama-server` by default; Claude (via LiteLLM) and
  Ollama drop in without touching the team code.
- **Engine + persona.** Boots and chats with a neutral demo persona; a private
  persona repo overlays prompts and registers its own specialists without forking.

```mermaid
flowchart LR
    D[Discord] --> CS[ConversationService]
    A[HTTP API + OpenAI shim] --> CS
    W[Web / desktop chat] --> CS
    CS --> MEM[(Deliberate memory<br/>+ identity)]
    CS --> TEAM{{Agent team<br/>lead → specialists}}
    TEAM --> BK[llama-server / LiteLLM / Ollama]
    MEM --> ST[(files · Qdrant · SQLite)]
    TEAM --> OBJ[(byte archive · knowledge)]
```

## Admin dashboard

A web dashboard to **inspect and edit everything the assistant remembers** — the
counterpart to deliberate memory. Browse users and their curated facts, read
sessions as a chat transcript, promote a session's takeaways into long-term
memory, manage the knowledge corpus, and edit the global persona and identity.
It also embeds a **streaming chat console** to talk to the brain as any user.
Built on the [`@carneirofc/ui`](https://github.com/carneirofc/deedlit.dev) design
system with light/dark themes. See [`web/`](https://github.com/carneirofc/magi-ai-assistant/blob/master/web/README.md) to run it.

<p align="center">
  <img src="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/02-dashboard.png" alt="MAGI admin dashboard" width="900">
</p>

<table>
  <tr>
    <td width="50%"><a href="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/04-user-detail.png"><img src="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/04-user-detail.png" alt="A user's memory — facts as editable cards"></a><br><sub><b>Memory</b> — a user's facts as editable cards, under tabs</sub></td>
    <td width="50%"><a href="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/05-session.png"><img src="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/05-session.png" alt="Session rendered as a chat transcript"></a><br><sub><b>Session</b> — the conversation window as a chat transcript</sub></td>
  </tr>
  <tr>
    <td width="50%"><a href="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/06-knowledge.png"><img src="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/06-knowledge.png" alt="Knowledge corpus"></a><br><sub><b>Knowledge</b> — corpus as table or cards, filtered by subject/tag</sub></td>
    <td width="50%"><a href="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/09-persona.png"><img src="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/09-persona.png" alt="Persona editor"></a><br><sub><b>Persona</b> — edit the global persona and bot identity</sub></td>
  </tr>
  <tr>
    <td width="50%"><a href="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/08-subjects.png"><img src="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/08-subjects.png" alt="Subject registry"></a><br><sub><b>Subjects</b> — the controlled vocabulary the corpus is grouped by</sub></td>
    <td width="50%"><a href="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/06-knowledge-dark.png"><img src="https://raw.githubusercontent.com/carneirofc/magi-ai-assistant/master/web/docs/screenshots/06-knowledge-dark.png" alt="Dark theme"></a><br><sub><b>Dark theme</b> — a click away, on every page</sub></td>
  </tr>
</table>

More views in the [admin UI README](https://github.com/carneirofc/magi-ai-assistant/blob/master/web/README.md#screenshots).

## Use as a library & extend

magi is meant to be *overlaid*, not forked. A persona repo depends on the engine
and adds its own persona + specialists without editing the public tree — this is
how a private persona overlay is built (full plan in
[docs/split-plan.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/split-plan.md); the frontend twin in
[docs/frontend-split.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/frontend-split.md)).

```toml
# your-persona/pyproject.toml
[project]
dependencies = ["magi-ai-assistant"]    # pin magi-ai-assistant==0.1.* for a release
                                         # (dist name — you still `import magi`)

[tool.uv.sources]                       # …or a live editable link during dev
magi-ai-assistant = { path = "../chatbot", editable = true }
```

Two seams, no forking:

```python
# register private specialists at your entrypoint, before build_team()
from magi.agent.members import register_member

@register_member
def build_myspecialist(model): ...      # your own agno Agent factory
```

- **Prompts are an overlay search path** — point a config dir at your persona's
  prompts; the bundled neutral demo prompts are the fallback
  (`magi/core/prompts.py`). Persona is data, not code.
- **The frontend mirrors this** — build your admin/chat UI on the published
  [`@carneirofc/magi-web`](https://github.com/carneirofc/magi-ai-assistant/blob/master/web/packages/magi-web/README.md) component + chat-runtime
  library.

**Releases.** Tag `v*` builds the engine and publishes it to PyPI as
[`magi-ai-assistant`](https://pypi.org/project/magi-ai-assistant/) — plus a
GitHub Release carrying the wheel/sdist
([`.github/workflows/publish-magi.yml`](https://github.com/carneirofc/magi-ai-assistant/blob/master/.github/workflows/publish-magi.yml)); tag
`magi-web-v*` publishes the frontend library to GitHub Packages
([`.github/workflows/publish-magi-web.yml`](https://github.com/carneirofc/magi-ai-assistant/blob/master/.github/workflows/publish-magi-web.yml)).
Tag `release-v*` ships both in lockstep
([`.github/workflows/release.yml`](https://github.com/carneirofc/magi-ai-assistant/blob/master/.github/workflows/release.yml)).

## Documentation

Full docs live in [`docs/`](https://github.com/carneirofc/magi-ai-assistant/tree/master/docs) — this README is just the map.

| Topic | Doc |
|---|---|
| Install & run, first chat, Open WebUI | [getting-started.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/getting-started.md) |
| Design, request lifecycle, diagrams | [architecture.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/architecture.md) |
| Deliberate memory (the centerpiece) | [memory.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/memory.md) |
| Discord / HTTP / OpenAI shim contracts | [channels.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/channels.md) |
| Desktop app client (embed or HTTP SDK) | [desktop.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/desktop.md) |
| Every configuration field | [configuration.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/configuration.md) |
| Team, members, tool catalog | [agent-and-tools.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/agent-and-tools.md) |
| Docker services, ports, ingestion | [infrastructure.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/infrastructure.md) |
| Split into engine + persona overlay; releasing both libraries | [split-plan.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/split-plan.md) · [frontend-split.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/frontend-split.md) |

Domain vocabulary is defined in [CONTEXT.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/CONTEXT.md); architecture decisions in
[docs/adr/](https://github.com/carneirofc/magi-ai-assistant/tree/master/docs/adr); the release history in [CHANGELOG.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/CHANGELOG.md).

## Run

```bash
python main.py api      # standalone HTTP service (+ OpenAI shim) for external clients
python main.py discord  # Discord bot (needs DISCORD_BOT_TOKEN)
python main.py desktop  # frameless native shell over the web frontend (uv sync --extra desktop)
python main.py admin    # operator admin API (memory + knowledge)
```

Every chat channel serves the same brain (`magi/channels/bootstrap.py`); only the
transport differs. Config is code-first: each channel's settings live in its
`configure_*` function in [`main.py`](https://github.com/carneirofc/magi-ai-assistant/blob/master/main.py), and defaults in
`magi/core/config.py`. Only *secrets* come from `.env` (`DISCORD_BOT_TOKEN`,
`API_AUTH_TOKEN`, `QDRANT_API_KEY`, …). Add `--docker` to any chat channel to
overlay the container-only deltas. Full walkthroughs — first chat, Open WebUI,
Docker, storage backends — are in [docs/](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/getting-started.md).

## Clients

- **HTTP API + OpenAI shim** — JSON over HTTP, session-scoped, with an
  OpenAI-compatible `/v1/chat/completions` so off-the-shelf UIs (Open WebUI,
  LibreChat) work unchanged. Streams `delta` events over SSE, carries media both
  ways. Contract in [docs/channels.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/channels.md).
- **Desktop SDK** — [`magi.client`](https://github.com/carneirofc/magi-ai-assistant/blob/master/src/magi/client/__init__.py) embeds the whole
  brain in a Python GUI (`embed(...)`, no server) or talks to a running API
  (`connect(...)`) behind one call surface; `SyncClient` wraps either in blocking
  methods for Tkinter/PyQt/wx. Runnable example:
  [`examples/desktop_chat.py`](https://github.com/carneirofc/magi-ai-assistant/blob/master/examples/desktop_chat.py). See
  [docs/desktop.md](https://github.com/carneirofc/magi-ai-assistant/blob/master/docs/desktop.md).
- **Native desktop shell** — `python main.py desktop` renders the web frontend in
  a chromeless, translucent window and serves it from one process, with a
  JS↔Python bridge.

```python
from magi.client import SyncClient, embed, connect

ui = SyncClient(embed(user_id="local"))                 # in-process, no server
# ui = SyncClient(connect("http://127.0.0.1:8000", user_id="local"))  # over HTTP
print(ui.send("hello").text)
for chunk in ui.stream("tell me more"):                 # streamed deltas
    ...
ui.close()
```
