scitex-cards — canonical YAML task store with pluggable adapters

scitex-cards keeps your tasks in one validated YAML store (a top-level tasks: list) and renders that single source of truth through pluggable adapters: a mermaid dependency-graph PNG, a read-only React-Flow web board, and a plain task listing. Part of SciTeX.

The store is PostgreSQL on 55432 and there is ONE store identity: an explicit store argument → $SCITEX_CARDS_DB. Nothing else — unset RAISES. There is deliberately no SQLite tier, no project scope and no bundled-example fallback: an unconfigured store is a configuration error, not a cue to invent a board.

Interfaces

Interface	Description
Python API	import scitex_cards as cards — scitex_cards — Python API
CLI	scitex-cards <command> — CLI Reference
MCP	AI-agent tools via fastmcp (on the roadmap)
Skills	AI-agent knowledge pages bundled at _skills/scitex-cards/

Getting Started

• Installation
  • Extras
  • Rendering backends
  • Verify
• Quick Start
  • Task schema
  • Where your task data lives

User Guide

• CLI Reference
  • Universal flags

API Reference

• scitex_cards — Python API
  • Quick Start
  • AgentDirectoryPort
  • AgentIdentityError
  • AgentInfo
  • EmptyAgentDirectory
  • TaskNotFoundError
  • TaskValidationError
  • ack_notifications()
  • add_task()
  • canonical_agent_id()
  • comment_task()
  • complete_task()
  • dedup_agents()
  • delete_task()
  • dm_list()
  • dm_send()
  • dm_send_document()
  • get_task()
  • health()
  • help_clear()
  • help_wait()
  • list_tasks()
  • parse_agent_id()
  • poll_notifications()
  • reassign_task()
  • reopen_task()
  • rescore_task()
  • resolve_agent_directory()
  • resolve_store()
  • resolve_task()
  • restore_task()
  • set_collaborator()
  • set_edge()
  • set_subscriber()
  • summarize_tasks()
  • update_task()

Quick example

Python API:

import scitex_cards as cards

tasks = cards.load_tasks("tasks.yaml")    # validates id / title / status
mermaid_src = cards.build_mermaid(tasks)  # YAML -> flowchart TB
engine = cards.render(mermaid_src, "tasks.png")
print(f"rendered via {engine}")

CLI:

scitex-cards render-graph -o tasks.png      # YAML -> dependency PNG
scitex-cards list-tasks --json              # resolved tasks, machine-readable
scitex-cards board --port 8051              # read-only web board (needs [web])

Four Freedoms for Research

0. The freedom to run your research anywhere – your machine, your terms.

1. The freedom to study how every step works – from raw data to final manuscript.

2. The freedom to redistribute your workflows, not just your papers.

3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 – because research infrastructure deserves the same freedoms as the software it runs on.

Indices and tables

• Index

• Module Index

• Search Page