AI TaskVector

Your local-first AI assistant and agent platform that runs explicitly on your machine.

• Co-pilot mode: research, coding/file editing, spreadsheet tasks execution (.xlsx), workflow creation, process automations, etc.
• Long-polling mode: works while you sleep using messengers, tools, custom workflows, calendar (iCal), RL training;

It also includes:

• AI Factory: create custom AI agents and teams with a built-in workflow assistant;
• Custom automations: develop new workflows in minutes with the co-pilot using own low-code framework;
• Local models: works with llama.cpp and Ollama;
• Tools and integrations: built-in packages, MCP support;
• RAG: local knowledge base, retrieval, and chat memory;
• Observability: built-in visibility into workflows, sources, and agent activity;
• Channels: WEB & Desktop: (Flet), Messengers: Telegram;
• Workflow server & Inference: API for external integrations.

Workflow server: RAG, Agent runtime, etc...	Built-in UI: Workflow Designer Agent
Long-polling: Agent chatting over Tg	Built-in UI: Coder Agent

Quick start

Rename: config/app_settings_example.json -> config/app_settings.json

MacOS / Linux

Install:

curl -fsSL https://github.com/PaulSff/ai-taskvector/raw/master/install.sh | bash

Run:

cd ai-taskvector
./run.sh

Windows

Install:

irm https://github.com/PaulSff/ai-taskvector/raw/master/install.ps1 | iex

Run:

cd ai-taskvector
.\run.ps1

Docker:

docker compose build
docker compose up

Then open the Flet GUI in your browser at http://localhost:8550. The app is configured to use the Ollama service automatically via OLLAMA_HOST.

Pull a model in Ollama (one-time):

docker compose exec ollama ollama pull gemma4:31b-cloud

Models are stored in a persistent volume (ollama_data).

Build and run the app image only

docker build -t ai-taskvector .
docker run --rm -p 8550:8550 \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -e SKIP_OLLAMA=1 \
  ai-taskvector

Open http://localhost:8550. If Ollama runs on your host, point the app at it with:

docker run --rm -p 8550:8550 \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -e SKIP_OLLAMA=1 \
  ai-taskvector

Environment variables

Variable	Description
OLLAMA_HOST	Ollama server URL (default: http://127.0.0.1:11434). In Compose, set to http://ollama:11434.
OLLAMA_MODEL	Default model name (e.g. gemma4:31b-cloud) when not set in GUI settings.
OLLAMA_API_KEY	Optional (for Ollama Cloud)

Docker Files

• Dockerfile — TaskVector install (server + RAG + Flet GUI + units);
• docker-compose.yml — TaskVector + Ollama service; Flet runs in web mode on port 8550.

---

Install manually

0. Clone TaskVector to your machine

git clone https://github.com/PaulSff/ai-taskvector.git

1. Install TaskVector, GUI and packages

cd ai-taskvector
pip install -e ".[rag,gui,llm-integrations,messengers-integrations,units-web,units-semantics,units-messengers,units-time,units-network,units-coding,mcp-integrations]"

2. Pull LLM Make sure you have installed Ollama or llama.cpp (set up llama.cpp for completely local inference)

Currently, we support Ollama. Follow the instructions to download Ollama and pull LLMs (No other services are required, but the models themselves. Everything else is provided by TaskVector (memory, tools, etc.).

3. Run workflow server and GUI

Run workflow server:

 python services/server/workflow_server.py

Run GUI:

• Desktop:

flet run gui/main.py

• WEB:

flet run gui/main.py --web -p 8550

In your WEB browser, open: http://localhost:8550

Development mode (allows to follow the LLMs context, prompts, etc.):

python -m gui.main -dev

Configuration

• config/app_settings.json - general settings rename: app_settings_example.json
• config/prompts/<role>.json - role prompt used on agent workflow execution
• rag/ragconf.yaml - rag config
• roles/<role>/role.yaml - agent role config
• tools/<tool>/tool.yaml - agent tool config
• mydata/- default folder for your data (set up any folder)
• rag/.rag_index_data/
  • chroma_db/ - default db folder
  • rag_index_state.json - mydata changes state
• chat_history/ - AI chat conversations and metadata ranked

Create your custom AI agent package in one command

You can create a new agent in one command by cloning the Analyst role package.

Execute From the repo root:

  python agents/roles/clone_role.py --new-role operator \
    --character-name Alex \
    --responsibility "Responsible for X..." \
    --intro "Hello, I'm Admin at TaskVector..." \
    --tools grep read_file formulas_calc ...     

• --new-role (mandatory) - new agent role name (e.g. administrator, sales manager, account manager, etc.)
• --character-name(mandatory) - any human-like name for the character to interact with
• --responsibility - responsibility descritpion
• --intro - one sentence introduction
• --tools - a set of tools available for the agent (pick up the tools from here: agents/tools)
• --intro-body e.g. "You do servers administration jobs and address users requests.."
• --conversational-behaviour e.g. "Start with a short lead sentence, then go deeper..."
• --reasoning e.g. "Break down tasks..."

Once the new role is created, adjust the prompt to adapt the agent behaviour: agents/roles/<new_role>/prompts.py. Modify these particular sections:

• <NEW_ROLE>_SECTION_ROLE_AND_INTRO_BODY = """ ... """.
• <NEW_ROLE>_SECTION_CONVERSATIONAL_BEHAVIOUR = """ ... """
• <NEW_ROLE>_SECTION_REASONING = """...""" These lines will be used to auto-generate config/<role>.json prompt config passed on input of the role worklflow execution.

Restart the app and enjoy interacting with your agent through the chat. The config/prompts/<role>.json is built automaticaly on startup. Configure the agent with the roles/<role>/role.yaml.

---

• Workflows:
  • You can either create a workflow from scratch or import one.
  • Drop in a workflow graph TaskVector native or external (Node-RED, PyFlow, n8n, ..). External ones are translated to TaskVector canonical workflow format on import;
  • Modify the workflow (export back if needed)
  • Run the process inline (Python only)
  • Testing: Add a Debug unit with /debug.log in params to log the output. Use Template unit to pass mock/test data into the workflow. A simple test workflow would be as follows: Template -> Inject -> YourUnitToTest -> Debug
• RAG:
  • Knowledge Base: Upload files, search data (e.g. you can upload node-red repo for the AI agents to use their workflow library or an XLSX spreadsheet to make calculations using formulas, etc.).
  • Agent Long Memory: Make sure the chat_history folder is under the RAG (e.g. mydata/chat_history) for the agents to remember conversations that happened in the past.
• RL training (is being eveloped):
  • Load/edit training config (goal, rewards, callbacks).
  • Run training or test Best model.

---

Creating new Units and Tools

• Follow this guide to create custom units (nodes): units/CREATING-NEW-UNIT.md
• Explore new tools development guide: agents/tools/README.md

LLM Integrations

We created a unified LLM client interface (llm_integrations/client.py) to support multiple LLM providers. Each provider has its own adapter in llm_integrations/<provider>.py, which converts the provider's API to a uniform interface. Create a new adapter for your provider, use the llm_integrations/ollama.py as a reference.

Messengers integrations

• Follow the Telegram example (messengers_integrations/telegram) to integrate new provider into the system.
• Create a unit for the messenger to interact with from the workflow. Reference: units/messengers/telegram_bot
• Create a gateway for your messenger. Use the telegram gateway (agents/chat/telegram_gateway) as a reference to wire new messenger into the agents flow.

Contribution

Thanks for considering a contribution — we welcome fixes, features, docs, tests, and new units/agents. Fork the repo and follow the contribution guidelines.

Stage

Beta version! Use it at your own risk.

Quick Links

• Contribution Guidelines
• Unit Creation Guide
• Tool Development Guide

License

MIT — use and modify for your projects.