Assistant

The HSYCO Assistant is an AI interface integrated with HSYCO. It can answer questions, inspect selected HSYCO context, use tools, read uploaded files, and create downloadable files.

HSYCO exposes four AI entry points:

• Manager Assistant - available inside the Manager for administrators and developers.
• Client Assistant - available inside HSYCO projects when a UI object opens it with the ai-assistant action.
• AIGEN I/O Server - available to EVENTS, JavaScript, Java code, and project logic through datapoints.
• MCP Server - available to external MCP clients, with Manager approval before protected HSYCO tools can run.

The Manager and Client Assistant surfaces use the same chat transcript layout, session history, file upload controls, and generated download links. The main difference is the context and tools available to the assistant.

The AIGEN I/O Server uses the same provider and tool infrastructure, but exposes generation through I/O Server datapoints instead of a chat transcript. Use it when AI requests must be driven by HSYCO logic or automations.

The MCP Server exposes the same shared HSYCO tools to external AI clients. Use it when an external MCP-compatible client should work with HSYCO through a Manager-approved session.

Providers and models

The Assistant uses the AI providers configured on the HSYCO server. Supported providers include Anthropic, OpenAI, OpenAI-compatible endpoints, Google Gemini, and Ollama. The model selector shows the models available for the configured providers.

AI profile order defines priority for automatic Manager features. For example, bug-report title generation uses the Mini model of the first available Manager-enabled profile. Reorder profiles in Manager Settings and save the configuration to change this priority.

The selected model is stored with the chat session. When a saved session is reopened, the session uses the model that was last used in that session.

Some models expose a reasoning selector. The available reasoning levels depend on the selected provider and model.

Ollama and OpenAI-compatible profiles can map endpoint-specific mini_model, base_model, advanced_model, and compaction_model IDs. Mini utility work such as title generation defaults to Base, while Compaction defaults to Advanced; missing or unavailable mappings use the first model returned by the endpoint. Manager Settings discovers model IDs and reasoning choices through session-scoped callback datasources.

Sessions

Assistant conversations are saved as sessions. A session stores the transcript, selected model, status, statistics, and references to generated files while they are still available.

The session list can be used to reopen previous conversations. Starting a new session clears the current draft and starts a separate conversation.

The Assistant may summarize older messages to make room in long conversations. If summarization fails, your message is saved and the Assistant continues when enough room remains. Otherwise, retry compaction or select a model with a larger context window.

Tool activity

When the assistant needs live HSYCO data or needs to perform an operation, it may call a tool. Tool activity is shown in the transcript as a work block, separate from the final answer.

Tool calls can read HSYCO documentation, inspect runtime status, read project or client context, read uploaded files, and create downloadable files. The exact tool set depends on whether the request is running in the Manager, in a client project, through the AIGEN I/O Server, or through an MCP client.

See Assistant Tools for the complete tool list, grouped by bundle and surface availability.

Uploading files

Use the paperclip button to attach one or more files. Each file appears as a tag in the composer.

While a file is uploading, its tag shows a progress indicator and a remove button. The remove button cancels the upload when possible. If the upload has already completed, removing the tag deletes the uploaded file from the Assistant cache.

Uploaded files are scoped to the current Assistant session. The assistant does not automatically read every uploaded file. When the user asks about the files, the assistant can list and read them through its file tools.

Attachments submitted with a message remain visible while the assistant is working. A successful run removes only the files submitted with that message. If the run fails, those files remain selected so the message can be retried; files added while a run is active are left for the next message.

Text formats such as XML, HTML, CSS, JSON, and CSV are read as text. Supported PDF and Office documents, including XLS and XLSX workbooks, are passed to providers that support native file input. Other binary formats may expose only filename, MIME type, and size.

Downloading generated files

When the assistant creates a file, the filename is shown as a download link in the assistant response. Click the filename to download the generated file.

Generated files can include text files, CSV files, JSON files, scripts, reports, or other file types the assistant creates from text or binary data.

File cache

Uploaded files and generated downloadable files are stored in memory on the HSYCO server. They are not permanent files in the HSYCO file system.

Uploaded files:

• are scoped to one Assistant session;
• expire 4 hours after upload;
• are deleted immediately when the user removes the file tag;
• are removed when the server restarts;
• are limited to 128 stored uploaded files, with the oldest files evicted when the limit is exceeded.

Generated downloadable files:

• expire 1 hour after creation;
• are removed when the server restarts;
• are limited to 64 stored generated files, with the oldest files evicted when the limit is exceeded.

Expired file cleanup happens when the Assistant stores, deletes, lists, reads, or resolves files.

note

Do not treat Assistant file links as permanent storage. Download generated files or save important uploaded files elsewhere when they must be preserved.

Security and privacy

Assistant requests may send selected conversation text, uploaded file content, and contextual HSYCO data to the configured AI provider. Only use the Assistant with providers and files that are appropriate for the installation.

The Client Assistant exposes a limited view of the current project page. The Manager Assistant has broader administrative context and tools. The AIGEN I/O Server exposes only the tools enabled by its I/O Server configuration. MCP clients require Manager approval before protected HSYCO tools can run.