ToDoWrite Models API Reference

This section provides a comprehensive reference for ToDoWrite Models implementation.

Core Imports

from todowrite import (
    # ToDoWrite Models (12 layers)
    Goal, Concept, Context, Constraints,
    Requirements, AcceptanceCriteria, InterfaceContract,
    Phase, Step, Task, SubTask, Command,
    Label,

    # Database utilities
    Base, create_engine, sessionmaker,

    # Schema validation
    initialize_database, validate_model_data,
)

Database Operations

Initialize Database

from todowrite.core.schema_validator import initialize_database

# Initialize with SQLite
initialize_database("sqlite:///project.db")

# Initialize with PostgreSQL
initialize_database("postgresql://user:pass@localhost/project")

Create Session

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

engine = create_engine("sqlite:///project.db")
Session = sessionmaker(bind=engine)
session = Session()

Models

All models follow ToDoWrite Models patterns with integer primary keys.

Goal Model

class Goal(**kwargs)[source]

ToDoWrite Goal model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

extra_data

labels

tasks

phases

constraints

concepts

contexts

classmethod create(title, description='', owner='', severity='', work_type='', assignee='')[source]

Create a new Goal instance with default values.

Return type:: Goal

start_work()[source]

Mark goal as started by setting started_on to current timestamp.

Return type:: None

complete_work()[source]

Mark goal as completed by setting ended_on to current timestamp.

Return type:: None

set_progress(progress)[source]

Set progress percentage (0-100).

Return type:: None

is_completed()[source]

Check if goal is marked as completed.

Return type:: bool

is_started()[source]

Check if goal is marked as started.

Return type:: bool

add_label(label)[source]

Add a label to this goal.

Return type:: None

remove_label(label)[source]

Remove a label from this goal.

Return type:: None

add_task(task)[source]

Add a task to this goal.

Return type:: None

remove_task(task)[source]

Remove a task from this goal.

Return type:: None

add_phase(phase)[source]

Add a phase to this goal.

Return type:: None

remove_phase(phase)[source]

Remove a phase from this goal.

Return type:: None

to_dict()[source]

Convert goal to dictionary representation.

Return type:: dict[str, object]

classmethod from_dict(data)[source]

Create Goal instance from dictionary.

Return type:: Goal

save(session)[source]

Save this goal to the database.

Return type:: None

delete(session)[source]

Delete this goal from the database.

Return type:: None

classmethod find_by_id(session, goal_id)[source]

Find a goal by ID.

Return type:: Goal | None

classmethod find_by_title(session, title)[source]

Find a goal by title.

Return type:: Goal | None

classmethod all(session)[source]

Get all goals.

Return type:: list[Goal]

classmethod find_completed(session)[source]

Get all completed goals.

Return type:: list[Goal]

classmethod find_active(session)[source]

Get all active (not completed) goals.

Return type:: list[Goal]

get_work_duration()[source]

Get the duration between start and completion in ISO format.

Return type:: str | None

get_summary()[source]

Get a brief summary of the goal.

Return type:: str

validate()[source]

Validate goal data and return list of errors.

Return type:: list[str]

is_valid()[source]

Check if goal data is valid.

Return type:: bool

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

Concept Model

class Concept(**kwargs)[source]

ToDoWrite Concept model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

extra_data

labels

goals

contexts

requirements

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

Context Model

class Context(**kwargs)[source]

ToDoWrite Context model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

extra_data

labels

concepts

goals

requirements

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

Constraints Model

Requirements Model

AcceptanceCriteria Model

class AcceptanceCriteria(**kwargs)[source]

ToDoWrite AcceptanceCriteria model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

extra_data

labels

requirements

interface_contracts

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

InterfaceContract Model

class InterfaceContract(**kwargs)[source]

ToDoWrite InterfaceContract model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

extra_data

labels

acceptance_criteria

phases

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

Phase Model

class Phase(**kwargs)[source]

ToDoWrite Phase model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

extra_data

labels

goals

steps

interface_contracts

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

Step Model

class Step(**kwargs)[source]

ToDoWrite Step model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

extra_data

labels

phases

tasks

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

Task Model

class Task(**kwargs)[source]

ToDoWrite Task model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

extra_data

labels

goals

steps

sub_tasks

property commands

Get all commands from all subtasks for this task.

Provides complete execution plan visibility by aggregating all commands across all subtasks belonging to this task.

Returns:: List of all Command objects from all subtasks in execution order.

property total_commands_count: Get total number of commands across all subtasks.

property completed_commands_count: Get count of completed commands across all subtasks.

property execution_progress_percentage: Calculate execution progress as percentage based on completed commands.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

SubTask Model

class SubTask(**kwargs)[source]

ToDoWrite SubTask model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

extra_data

labels

tasks

commands

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

Command Model

class Command(**kwargs)[source]

ToDoWrite Command model for hierarchical task management.

id

title

description

status

progress

started_on

ended_on

owner

severity

work_type

assignee

acceptance_criteria_id

cmd

cmd_params

runtime_env

output

artifacts

labels

sub_tasks

property runtime_env_dict: Get runtime environment as dictionary.

property artifacts_list: Get artifacts as list.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

mark_completed()[source]

Mark command as completed with current timestamp.

Return type:: None

updated_at

mark_started()[source]

Mark command as started with current timestamp.

Return type:: None

Label Model

class Label(**kwargs)[source]

ToDoWrite Label model for categorizing and tagging other models.

id

name

goals

concepts

contexts

constraints

requirements

acceptance_criteria

interface_contracts

phases

steps

tasks

sub_tasks

commands

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at

updated_at

Relationships

Many-to-Many Associations

All models support many-to-many relationships through join tables:

# Create a goal
goal = Goal(title="Launch Product", owner="team")
session.add(goal)

# Create tasks
task1 = Task(title="Design UI", owner="designer")
task2 = Task(title="Write tests", owner="developer")
session.add(task1)
session.add(task2)

# Associate tasks with goal
goal.tasks.append(task1)
goal.tasks.append(task2)

# Create and associate labels
urgent_label = Label(name="urgent")
design_label = Label(name="design")
session.add(urgent_label)
session.add(design_label)

task1.labels.extend([urgent_label, design_label])
task2.labels.append(urgent_label)

session.commit()

Query Patterns

# Get all goals
goals = session.query(Goal).all()

# Get tasks for a specific goal
goal_tasks = session.query(Task).filter(Task.goals.contains(goal)).all()

# Get tasks with specific labels
from sqlalchemy.orm import joinedload
urgent_tasks = session.query(Task).options(
    joinedload(Task.labels)
).filter(Task.labels.any(Label.name == "urgent")).all()

Schema Validation

Validate Model Data

from todowrite.core.schema_validator import validate_model_data

# Validate a task dictionary
task_data = {
    "title": "New Task",
    "description": "Task description",
    "owner": "team",
    "severity": "high"
}

is_valid, errors = validate_model_data(Task, task_data)
if not is_valid:
    print("Validation errors:", errors)

Complete Model List

The 12 ToDoWrite Models are:

Goal - High-level project objectives
Concept - Abstract ideas and requirements
Context - Background information and constraints
Constraints - Technical and business constraints
Requirements - Specific functional requirements
AcceptanceCriteria - Definition of done criteria
InterfaceContract - API and interface contracts
Phase - Project phases and milestones
Step - Individual steps within phases
Task - Specific tasks with owners and status
SubTask - Breakdown of tasks into smaller units
Command - Executable commands and scripts

Plus the Label model for many-to-many tagging.

For detailed model documentation, see ToDoWrite Models.