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

pip install senpai-assistant

The package requires Python 3.12 or newer.

CLI

After installation, run the assistant with:

senpai-assistant --help

You can also run the module directly:

python -m senpai_assistant --help

Python API

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",
    screen_id="test_center",
    screen_context={"active_tab": "sensei", "selected_connector_id": "connector-1"},
)

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. screen_id and screen_context are optional per-message host UI context fields. Use them from Chatbot Dojo to tell Senpai which screen the user is viewing and a small, sanitized set of visible details such as the active tab, selected run/profile/rule id, or visible error. Senpai includes metadata for known screen ids like setup_guide, test_center, chatbot_connectors, projects, tracer_dashboard, sensei_dashboard, sensei_check_dashboard, sensei_check_rules, test_case, yaml_editor, custom_connector_editor, and profile_settings. Avoid passing HTML, DOM dumps, credentials, API keys, large logs, or personal data that is not needed for the answer.

The public package exports:

• Assistant
• ScreenInfo
• create_assistant_for_paths(...)
• configure_runtime_root(...)
• get_screen_info(...)
• get_runtime_root()
• list_screen_registry()
• 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.

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