Goal Tracking

Track progress toward completion

GoalTracker monitors progress toward defined goals. Helps you (and agents) understand how close you are to completion.

Basic Usage

from splinter.coordination import GoalTracker, Goal

tracker = GoalTracker()

# Define goal with criteria
tracker.set_goal(Goal(
    goal_id="article",
    description="Publish a blog post about AI trends",
    success_criteria=["Research", "Draft", "Review", "Publish"],
))

# Mark progress
tracker.mark_criterion_met("article", "Research")
tracker.mark_criterion_met("article", "Draft")

# Check status
print(tracker.get_progress("article"))  # 0.5 (50%)
print(tracker.is_achieved("article"))   # False

Goal Structure

goal = Goal(
    goal_id="article",
    description="Write and publish an article",
    success_criteria=["Research", "Draft", "Review", "Publish"],
    priority=1,              # Higher = more important
    deadline=datetime(...),  # Optional deadline
    metadata={"topic": "AI"},
)

Updating Progress

# Mark criterion complete
tracker.mark_criterion_met("article", "Research")

# Or update progress directly
tracker.update_progress("article", 0.25)

# Add notes
tracker.add_note("article", "Research phase found 10 relevant sources")

Sub-Goals

Break big goals into sub-goals:

# Main goal
tracker.set_goal(Goal(goal_id="launch", description="Launch product"))

# Sub-goals
tracker.set_goal(Goal(goal_id="launch.backend", parent="launch"))
tracker.set_goal(Goal(goal_id="launch.frontend", parent="launch"))
tracker.set_goal(Goal(goal_id="launch.docs", parent="launch"))

# Parent progress updates automatically
tracker.mark_achieved("launch.backend")
print(tracker.get_progress("launch"))  # ~0.33

Checking Status

# Is goal achieved?
if tracker.is_achieved("article"):
    print("Goal complete!")

# Get all goals
all_goals = tracker.get_all_goals()

# Get incomplete goals
incomplete = tracker.get_incomplete_goals()

# Get goals by priority
urgent = tracker.get_goals_by_priority(min_priority=5)

Goal Events

def on_goal_achieved(goal_id):
    print(f"Goal {goal_id} achieved!")

def on_progress(goal_id, progress):
    print(f"Goal {goal_id}: {progress*100:.0f}%")

tracker.on_achieved(on_goal_achieved)
tracker.on_progress(on_progress)

Integration with Workflow

from splinter.workflow import Workflow

workflow = Workflow(workflow_id="pipeline")

tracker = GoalTracker()
tracker.set_goal(Goal(
    goal_id="complete",
    success_criteria=["researcher", "writer", "reviewer"],
))

# Auto-update on agent completion
workflow.on_agent_complete(lambda agent_id: 
    tracker.mark_criterion_met("complete", agent_id)
)

Best Practices

Define goals before starting

Clear goals help agents stay focused.

Use meaningful criteria

“Research complete” is better than “Step 1 done”.

Break large goals into sub-goals

Easier to track and gives better progress visibility.

Track time-based metrics

How long did each criterion take?