Zongsoft.Intelligences 0.8.0

Zongsoft.Intelligences Plugin Library

English | 简体中文

Overview

Zongsoft.Intelligences is the AI plugin library for the Zongsoft open-source framework. It provides AI integration through the Ollama protocol stack.

Install Ollama

On Windows 11, make sure WSL 2 and Podman are installed successfully.

Make sure the Podman virtual machine is running. You can verify it with the following commands:

podman machine list     # List virtual machines
podman machine info     # Show virtual machine information
podman machine start    # Start the default virtual machine

💡 Tip: Docker and Podman use almost the same commands. Replace podman with docker when using Docker.

Install Ollama in Podman

Follow the Ollama article Ollama is now available as an official Docker image and run the following command in PowerShell to install the Ollama image.

podman run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

After the download and installation complete, verify it with the following command. The model list is empty at this point:

podman exec -it ollama ollama list

Install a Model

Find the large language model you need in the official Ollama model library at https://ollama.com/search.

💡 For local development and testing, Qwen (qwen3:0.6b) is recommended. It is only 523MB and can run smoothly on low-spec machines without a GPU.

podman exec -it ollama ollama pull qwen3:0.6b

After the download and installation complete, verify it with the following commands:

# List local models
podman exec -it ollama ollama list

# Run the qwen3:0.6b model
# When it starts successfully, it enters interactive mode. Use /bye to exit.
podman exec -it ollama ollama run qwen3:0.6b

# List running models
podman exec -it ollama ollama ps

Ollama Connection Settings (OllamaConnectionSettings)

OllamaConnectionSettings has no TOptions constraint. Server, Model, History and Expiration are read through typed properties, while unknown text entries remain in the main dictionary. The raw indexer returns only explicit values; defaults such as Expiration are not inserted into the complete Value.

OllamaClientFactory requires an actual OllamaConnectionSettings instance. When starting from Settings or generic ConnectionSettings, rebuild it through OllamaConnectionSettingsDriver.Instance.GetSettings(settings.Name, settings.Value) before passing it to the factory. See the Core settings contract for dictionary and text semantics.

Run and Debug

If the directory that contains Zongsoft.Intelligences.dll in the host application also contains a preludes subdirectory, new chat sessions look in that directory for a text file whose name starts with the assistant name and use it as the session prelude. See the ChatSessionPreludeLoader.cs source code for details.

This extension library provides both command-line and RESTful API access.

Command Line

1. Run the deploy.cmd deployment command from the terminal project.
2. Start the compiled local terminal host program.

   If Ollama is not installed locally, update the connection address in the Zongsoft.Intelligences.option configuration file for this plugin.

Commands

• List AI assistants:

  ai.assistant
  

• Activate a specific AI assistant:

  Note: subsequent commands are based on the AI assistant selected by this command.

  # Set the AI assistant configuration. The argument is the connection name in the configuration file.
  ai.assistant ollama
  

• Model commands:

  # List local models
  ai.assistant.model.list
  
  # List running models
  ai.assistant.model.list --running
  
  # Show model information
  ai.assistant.model.info "qwen3:0.6b"
  
  # Download and install a model
  ai.assistant.model.install "qwen3:0.6b"
  # Delete and uninstall a model
  ai.assistant.model.uninstall "qwen3:0.6b"
  

• Session commands:

  # Create a new session
  ai.assistant.chat.open
  # Enter a specific session
  ai.assistant.chat.open 'session|chatroom'
  
  # Close the current session
  ai.assistant.chat.close
  # Close a specific session
  ai.assistant.chat.close 'session|chatroom'
  
  # Clear the current session history
  ai.assistant.chat.clear
  # Clear a specific session history
  ai.assistant.chat.clear 'session|chatroom'
  
  # Show the current session history
  ai.assistant.chat.history
  # Show a specific session history
  ai.assistant.chat.history 'session|chatroom'
  

• Chat commands:

  # Chat
  ai.assistant.chat "content"
  # Chat and return plain text
  ai.assistant.chat --format:text "content"
  
  # Chat with asynchronous streaming
  ai.assistant.chat --streaming "content"
  # Chat with asynchronous streaming in plain text
  ai.assistant.chat --streaming --format:text "content"
  
  # Enter interactive chat mode
  ai.assistant.chat --interactive
  

Interactive mode sends each entered line as a user message. exit, quit and EOF leave the chat. Both input and streamed responses observe the command cancellation token; the command does not own or dispose the terminal input. See Terminal input.

RESTful API

• Get the AI assistant list:

  GET /ai/assistants

• Get a specific AI assistant:

  GET /ai/assistants/{name}

• Get the model list:

  GET /ai/assistants/{name}/models

• Get model details:

  GET /ai/assistants/{name}/models/{id}

• Get the session list:

  GET /ai/assistants/{name}/chats

• Get session details:

  GET /ai/assistants/{name}/chats/{id}

• Create a new session:

  POST /ai/assistants/{name}/chats

• Close a session:

  DELETE /ai/assistants/{name}/chats/{id}

• Get the chat history of a session:

  GET /ai/assistants/{name}/chats/{id}/history

• Clear the chat history of a session:

  DELETE /ai/assistants/{name}/chats/{id}/history

• Chat without session history:

  POST /ai/assistants/{name}/chats/chat

• Chat with session history:

  POST /ai/assistants/{name}/chats/{id}/chat

Tip: chat.html in the api project is an example for calling the chat API. It uses Server-Sent Events.

For the complete API, see Zongsoft.Intelligences.Web.http in the api project.

• {name} is the assistant name, such as ollama.
• {id} is the session ID.

Plugin-Based Integration

Compose this feature through the host; a package reference supplies compile-time APIs, while plugin loading also requires deployed manifests and runtime assets. See the complete plugin workflow.

The manifest registers connection-setting drivers and the AI command group. Configure the provider/model before resolving an assistant; add the Web package only on HTTP hosts. The current source .deploy still lists older AI dependencies: compare it with the selected package's .csproj/lockfile before deployment rather than assuming those versions match the current API.

Add this fragment to an existing host .deploy (retain Main and the host’s other base manifests; do not replace the whole file):

[plugins zongsoft intelligences]
nuget:Zongsoft.Intelligences

Run dotnet deploy against a test deployment as explained in the workflow, with the host's framework, platform, architecture and, where needed, site. Pin compatible versions in real deployments; application dependencies such as databases, caches or commercial runtimes are still separate prerequisites.

Additional artifacts listed by the deployment manifest include Zongsoft.Intelligences.option, Zongsoft.Intelligences.plugin. Retain assemblies, dependencies and satellite resource directories as well. Restart the host after deployment, check plugin loading and service/driver registration, then verify the workflow above; copied files alone do not prove that the feature is active.