Metadata-Version: 2.4
Name: senpai-assistant
Version: 0.6.0
Summary: Assistant tooling for SENSEI projects.
Project-URL: Homepage, https://github.com/miso-booster/Senpai-Assistant
Project-URL: Repository, https://github.com/miso-booster/Senpai-Assistant
Project-URL: Issues, https://github.com/miso-booster/Senpai-Assistant/issues
Project-URL: Changelog, https://github.com/miso-booster/Senpai-Assistant/blob/main/CHANGELOG.md
Keywords: assistant,sensei,langchain,langgraph
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: langchain>=1.0.0
Requires-Dist: langchain-openai>=1.0.0
Requires-Dist: langgraph>=1.0.0
Requires-Dist: langgraph-checkpoint-sqlite>=2.0.11
Requires-Dist: openai>=2.3.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: types-pyyaml>=6.0.12.20250915
Requires-Dist: pydantic>=2.12.2
Requires-Dist: numpy>=2.3.5
Requires-Dist: langchain-community>=0.3.31
Requires-Dist: sentence-transformers>=5.1.2
Requires-Dist: langchain-huggingface>=1.1.0
Requires-Dist: langchain-anthropic>=1.0.0
Requires-Dist: langchain-google-genai>=3.0.0
Requires-Dist: langchain-mistralai>=1.0.0
Requires-Dist: langchain-groq>=1.0.0
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: torch
Requires-Dist: torchvision
Requires-Dist: torchaudio
Requires-Dist: senpai-validators>=0.2.1

# Senpai Assistant

Senpai Assistant is a Python package for building and running a SENSEI-focused assistant. It provides a console entry point and a public Python API for host applications that need to create assistants over SENSEI project files, connector files, reference docs, embeddings, and an external conversation checkpointer.

## Installation

```bash
pip install senpai-assistant
```

The package requires Python 3.12 or newer.

## CLI

After installation, run the assistant with:

```bash
senpai-assistant --help
```

You can also run the module directly:

```bash
python -m senpai_assistant --help
```

## Python API

```python
from pathlib import Path

from senpai_assistant import create_assistant_for_paths

assistant = create_assistant_for_paths(
    user_path=Path("/path/to/users/user_1"),
    thread_id="thread-1",
    runtime_root=Path("/var/lib/senpai-assistant"),
    checkpointer=checkpointer,
)

response = assistant.send_message(
    "Create a profile for refund questions",
    active_project="shop_a",
)
```

`checkpointer` should be a LangGraph checkpointer provided by the host application. For local CLI-style usage without an external checkpointer, pass `require_checkpointer=False` to allow the SQLite fallback.
`active_project` is optional per message and may change from one turn to the next. Hosted applications can pass the project currently open in the UI so Senpai uses it as the default target for profile and rule tools for that message. If `active_project` is omitted, empty, or `None`, Senpai assumes there is no active project selected for that message and will not reuse a previously active host project.

The public package exports:

- `Assistant`
- `create_assistant_for_paths(...)`
- `configure_runtime_root(...)`
- `get_runtime_root()`
- `main`

`create_assistant_for_paths(...)` expects a SENSEI user directory containing `connectors/` and `projects/`. Projects are discovered from `user_path / "projects"`. In hosted deployments, pass an external LangGraph checkpointer so conversation state is not stored in local SQLite.

## Runtime Files

Senpai Assistant writes generated runtime artifacts under the configured runtime root. The resolution order is:

1. An explicit `runtime_root` argument.
2. The process-wide root set with `configure_runtime_root(...)`.
3. The `SENPAI_HOME` environment variable.
4. The default user data location for the current platform.

Embedding indexes are stored under that runtime root. Local CLI usage can fall back to SQLite, but application integrations should pass their own checkpointer.

## Releases

Releases are published from tags named `vX.Y.Z`. The tag version must match the version in `pyproject.toml`, and `CHANGELOG.md` must contain a matching `## [X.Y.Z]` section.

```bash
uv version 0.1.1
git add pyproject.toml uv.lock CHANGELOG.md
git commit -m "Release 0.1.1"
git tag v0.1.1
git push origin main --tags
```
