Code-Based AI Todo Workflow Engine (Ollama-Native)

AI-powered Todo Workflow Engine built with FastAPI, PostgreSQL, and Ollama. This system uses a tool-calling agent architecture with persistent memory and clean layered design.

---

Overview

This project implements a domain-specific AI workflow engine that allows users to manage todos using natural language.

The AI agent:

• understands user intent
• executes structured tools
• persists memory
• enforces domain rules
• maintains strict architectural boundaries

The system is deterministic, transaction-safe, and Docker-ready.

---

Core Stack

• FastAPI — API layer
• PostgreSQL — database
• Ollama — LLM provider
• SQLAlchemy — ORM
• Docker — containerization

---

Architecture

Client
 ↓
FastAPI (API Layer)
 ↓
Agent Engine (Ollama)
 ↓
Tools Layer
 ↓
Domain Layer
 ↓
Repository Layer
 ↓
PostgreSQL

Rules:

• Agent never accesses database directly
• Tools never access repositories
• Domain controls all business logic
• Repository controls persistence only

---

Key Features

• Natural language todo management
• Tool-calling AI agent
• Persistent conversation memory
• Multi-user isolation
• Transaction-safe operations
• Docker support
• Clean layered architecture

---

Project Structure

project-root/

├── app/
│   ├── server/
│   ├── agent/
│   ├── domain/
│   ├── storage/
│   ├── core/
│   ├── shared/
│   └── tests/

├── Dockerfile
├── docker-compose.yml
├── .gitignore
├── .dockerignore
├── .env.example
├── requirements.txt
└── migrations/

---

Database Tables

users

id
user_key
created_at

todos

id
user_id
title
description
is_completed
due_date
version
created_at
updated_at

conversations

id
user_id
role
content
tool_name
created_at

---

Agent Execution Flow

1 Load system prompt
2 Load memory
3 Add user message
4 Call Ollama

IF tool requested:
    Execute tool
    Save result
    Call Ollama again

Repeat until final response

---

Docker Usage

Start all services:

docker compose up --build

Services started:

• API server
• PostgreSQL database
• Ollama LLM server

---

Environment Variables

Example:

DATABASE_URL=postgresql+psycopg://postgres:postgres@db:5432/todo
OLLAMA_BASE_URL=http://ollama:11434
MODEL_NAME=llama3

---

Example Request

POST /chat

{
  "user_key": 123456,
  "message": "Add buy milk tomorrow"
}

Example Response:

{
  "success": true,
  "message": "Operation successful",
  "data": {
    "response": "Todo created"
  }
}

---

System Guarantees

• Transaction safety
• Memory persistence
• Clean architecture enforcement
• Deterministic execution
• Tool-controlled domain access

---

Running Locally (Without Docker)

pip install -r requirements.txt
uvicorn app.server.main:app --reload

---

Running With Docker

docker compose up --build

---

Purpose

This project demonstrates a clean implementation of an AI agent workflow engine using Ollama with proper architectural separation and persistent memory.

---

License

MIT License