TTA.dev - AI Development Toolkit

Production-ready agentic primitives and workflow patterns for building reliable AI applications.

🎯 What is TTA.dev?

TTA.dev is a curated collection of battle-tested, production-ready components for building reliable AI applications. Every component here has:

✅ 100% test coverage
✅ Real-world production usage
✅ Comprehensive documentation
✅ Zero known critical bugs

Philosophy: Only proven code enters this repository.

🤝 Relationship to TTA (The Game)

TTA.dev was originally extracted from the Therapeutic Text Adventure (TTA) project.

TTA.dev (This Repo): The reusable DevOps, infrastructure, and agentic primitives.
TTA (Game Repo): The narrative storytelling game built on top of this platform.

📦 Repository Structure

TTA.dev is organized into platform infrastructure packages and apps for end-user deployments:

TTA.dev/
├── platform/              # Infrastructure packages (7)
│   ├── primitives/        # Core workflow primitives
│   ├── observability/     # OpenTelemetry integration
│   ├── agent-context/     # Agent context management
│   ├── agent-coordination/# Multi-agent orchestration
│   ├── integrations/      # Pre-built integrations
│   ├── documentation/     # Docs automation
│   └── kb-automation/     # Knowledge base maintenance
│
├── templates/             # 🚀 Vibe Coding Templates (Start Here)
│   ├── basic-agent/       # Simple agent with cache/retry
│   └── workflow/          # Multi-step workflow
│
├── apps/                  # User-facing applications (1)
│   └── observability-ui/  # VS Code observability dashboard
│
├── config/                # Configuration files
├── data/                  # Data artifacts
│   └── ace_playbooks/     # ACE Agent Playbooks
├── docs/                  # Documentation
├── scripts/               # Automation scripts
└── tests/                 # Integration tests

🏗️ Platform Packages

Core Infrastructure (Production-Ready)

1. `tta-dev-primitives` → `platform/primitives/`

Core workflow primitives for building reliable, observable agent workflows.

Features:

🔀 Router, Cache, Timeout, Retry, Memory primitives
🔗 Composition operators (>>, |)
⚡ Parallel and conditional execution
📊 OpenTelemetry integration
💪 Comprehensive error handling
📉 Cost reduction via intelligent caching and routing

Installation:

uv add tta-dev-primitives

Quick Start: See GETTING_STARTED.md for a quick start guide.

📚 Full Documentation

2. `tta-observability-integration` → `platform/observability/`

OpenTelemetry integration for tracing, metrics, and logging across TTA.dev primitives.

Features:

📊 Automatic OpenTelemetry tracing and metrics
📝 Structured logging
📈 Prometheus-compatible metrics export
🛡️ Graceful degradation when observability backend is unavailable

Installation:

uv add tta-observability-integration

📚 Full Documentation

3. `universal-agent-context` → `platform/agent-context/`

Agent context management and orchestration for multi-agent workflows.

Features:

🧠 Centralized context management for agents
🔄 Context propagation across primitives
🔑 Secure handling of agent-specific data
🤝 Facilitates multi-agent coordination

Installation:

uv add universal-agent-context

📚 Full Documentation

Extended Platform (Active Development)

4. `tta-agent-coordination` → `platform/agent-coordination/`

Atomic DevOps Architecture for multi-agent coordination.

📚 Documentation

5. `tta-dev-integrations` → `platform/integrations/`

Pre-built integration primitives (Supabase, PostgreSQL, Clerk, JWT).

📚 Documentation

6. `tta-documentation-primitives` → `platform/documentation/`

Automated docs ↔ Logseq sync with AI metadata.

📚 Documentation

7. `tta-kb-automation` → `platform/kb-automation/`

Automated knowledge base maintenance (links, TODOs, flashcards).

📚 Documentation

📱 Applications

`tta-observability-ui` → `apps/observability-ui/`

LangSmith-inspired observability dashboard with VS Code webview integration.

Features:

📊 Real-time trace visualization
🔍 Primitive-aware debugging
🎯 VS Code integration (coming Phase 3)

📚 Documentation

🚀 Quick Start

For a comprehensive quick start guide, including installation and your first workflow, please refer to GETTING_STARTED.md.

📚 Documentation

Getting Started Guide - 5-minute quickstart
Primitives Catalog - Complete reference for all primitives
Agent Instructions - Guidance for AI agents working on TTA.dev
GitHub Copilot Instructions - Comprehensive Copilot configuration and best practices
Architecture Overview - System design and principles
Coding Standards - Development best practices
MCP Integration - Model Context Protocol guides
Workspace Organization - Repository structure and navigation guide

Additional Resources

PR Management Guide - Intelligent PR oversight and automation
PR Management Quick Reference - Quick commands and best practices
LLM Cost Guide - Free vs paid model comparison, pricing analysis
Cost Optimization Patterns - Production patterns for 50-70% cost reduction
Cline Integration - Enhanced Cline development experience
AI Libraries Comparison
Model Selection Guide
LLM Selection Guide
Examples

🧪 Testing

All packages maintain 100% test coverage with comprehensive test suites.

# Run all tests
uv run pytest -v

# Run with coverage
uv run pytest --cov=platform --cov=apps --cov-report=html

# Run specific package tests
uv run pytest platform/primitives/tests/ -v

🛠️ Development

Prerequisites

Python 3.11+
uv (recommended)
VS Code with recommended extensions (see .vscode/extensions.json)

Setup

# Clone repository
git clone https://github.com/theinterneti/TTA.dev
cd TTA.dev

# Install dependencies
uv sync --all-extras

# Run tests
uv run pytest -v

# Run quality checks
uv run ruff format .
uv run ruff check . --fix
uvx pyright platform/ apps/

VS Code Workflow

We provide VS Code tasks for common operations:

Press Cmd/Ctrl+Shift+P
Type "Task: Run Task"
Select from:
- 🧪 Run All Tests
- ✅ Quality Check (All)
- 📦 Validate Package
- 🔍 Lint Code
- ✨ Format Code
- 📊 PR Dashboard
- 🔍 PR Analytics
- 🏥 PR Triage
- 🏥 PR Health Check
- 💡 PR Recommendations

See full task list

PR Management

TTA.dev includes intelligent PR management tools:

# Dashboard - Visual overview of all open PRs
python scripts/pr_manager.py dashboard

# Analytics - Detailed metrics and insights
python scripts/pr_manager.py analyze

# Triage - Categorize and prioritize PRs
python scripts/pr_manager.py triage

# Health Check - Identify PRs needing attention
python scripts/pr_manager.py health-check

# Recommendations - Get actionable next steps
python scripts/pr_manager.py recommend

Features:

📊 Smart categorization (critical, ready-to-merge, stale, etc.)
🎯 Priority scoring (0-100) based on urgency and impact
🏥 Automated health monitoring
💡 Actionable recommendations
🔗 Integration with Logseq TODO system
🤖 Weekly automated monitoring via GitHub Actions

See PR Management Guide for details.

🤝 Contributing

We welcome contributions! However, only battle-tested, proven code is accepted.

Contribution Criteria

Before submitting a PR, ensure:

✅ All tests passing (100%)
✅ Test coverage >100% (for new code)
✅ Documentation complete
✅ Ruff + Pyright checks pass
✅ TODO compliance (100%) - All Logseq TODOs properly formatted
✅ Real-world usage validation
✅ No known critical bugs

TODO Compliance Requirement

All TODOs in Logseq journals must follow the TODO Management System:

Category tag required: #dev-todo or #user-todo
For #dev-todo: Must include type::, priority::, package:: properties
For #user-todo: Must include type::, audience::, difficulty:: properties

Validation:

# Check TODO compliance locally
uv run python scripts/validate-todos.py

# Expected output: 100.0% compliance

The CI will automatically validate TODO compliance on all PRs. Non-compliant TODOs will block the merge.

Contribution Workflow

Create feature branch

git checkout -b feature/add-awesome-feature

Make changes and validate

./scripts/validate-package.sh <package-name>

Commit with semantic message

git commit -m "feat(package): Add awesome feature"

Create PR

gh pr create --title "feat: Add awesome feature"

Squash merge after approval

See full contribution guide

📋 Code Quality Standards

Formatting

Ruff with 88 character line length
Auto-format on save in VS Code

Linting

Ruff with strict rules
No unused imports or variables

Type Checking

Pyright in basic mode
Type hints required for all functions

Testing

pytest with AAA pattern
100% coverage required
All tests must pass

Documentation

Google-style docstrings
README for each package
Examples for all features
Phase 3 Examples: See platform/primitives/examples/PHASE3_EXAMPLES_COMPLETE.md for InstrumentedPrimitive pattern guide

🚦 CI/CD

All PRs automatically run:

✅ Ruff format check
✅ Ruff lint check
✅ Pyright type check
✅ pytest (all tests)
✅ Coverage report
✅ Multi-OS testing (Ubuntu, macOS, Windows)
✅ Multi-Python testing (3.11, 3.12)

Merging requires all checks to pass.

📊 Project Status

Current Release: v0.1.0 (Initial)

Package	Version	Tests	Coverage	Status
tta-dev-primitives	0.1.0	12/12 ✅	100%	🟢 Stable
tta-observability-integration	0.1.0	TBD	TBD	🟢 Stable
universal-agent-context	0.1.0	TBD	TBD	🟢 Stable

Roadmap

v0.2.0: Add more workflow primitives (saga, circuit breaker)
v0.3.0: Enhanced observability features
v1.0.0: First stable release

🔗 Related Projects

TTA - Therapeutic text adventure game (private)
Augment Code - AI coding assistant
GitHub Copilot - AI pair programmer

📄 License

MIT License - see LICENSE for details

🙏 Acknowledgments

Built with:

Python
uv - Fast Python package installer
Ruff - Fast Python linter
Pyright - Type checker
pytest - Testing framework
GitHub Copilot - AI assistance

📧 Contact

Maintainer: @theinterneti
Issues: GitHub Issues
Discussions: GitHub Discussions

⭐ Star History

If you find TTA.dev useful, please consider giving it a star! ⭐

Last Updated: 2025-11-10

Logseq: [[TTA.dev/Readme]]

Name		Name	Last commit message	Last commit date
Latest commit History 659 Commits
.agent-notifications		.agent-notifications
.augment		.augment
.cline		.cline
.cursor		.cursor
.gemini		.gemini
.git-hooks		.git-hooks
.github		.github
.hindsight		.hindsight
.hypertool		.hypertool
.serena		.serena
.tta		.tta
.universal-instructions/claude-specific		.universal-instructions/claude-specific
.vscode		.vscode
.worktree		.worktree
_archive		_archive
apps		apps
config		config
data		data
docs		docs
local		local
logseq		logseq
platform		platform
platform_tta_dev		platform_tta_dev
scripts		scripts
src/integrations/tests		src/integrations/tests
templates/basic-agent		templates/basic-agent
tests		tests
tta_secrets		tta_secrets
.COORDINATION_NOTICE		.COORDINATION_NOTICE
.bandit.yaml		.bandit.yaml
.clinerules		.clinerules
.env.example		.env.example
.env.template		.env.template
.gga		.gga
.gitignore		.gitignore
.mcp.json		.mcp.json
.memory.md		.memory.md
.pre-commit-config.yaml		.pre-commit-config.yaml
.ruffignore		.ruffignore
.secrets.baseline		.secrets.baseline
.secrets.baseline.new		.secrets.baseline.new
.semgrepignore		.semgrepignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
GETTING_STARTED.md		GETTING_STARTED.md
MCP_TOOL_REGISTRY.md		MCP_TOOL_REGISTRY.md
PRIMITIVES_CATALOG.md		PRIMITIVES_CATALOG.md
README.md		README.md
ROADMAP.md		ROADMAP.md
VALIDATION_REPORT.md		VALIDATION_REPORT.md
VIBE_CODING.md		VIBE_CODING.md
conftest.py		conftest.py
hello.py		hello.py
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
pyrightconfig.json		pyrightconfig.json
pytest.ini		pytest.ini
tasks_github.json		tasks_github.json
uv.lock		uv.lock
workspace.code-workspace		workspace.code-workspace

theinterneti/TTA.dev

Folders and files

Latest commit

History

Repository files navigation

TTA.dev - AI Development Toolkit

🎯 What is TTA.dev?

🤝 Relationship to TTA (The Game)

📦 Repository Structure

🏗️ Platform Packages

Core Infrastructure (Production-Ready)

1. tta-dev-primitives → platform/primitives/

2. tta-observability-integration → platform/observability/

3. universal-agent-context → platform/agent-context/

Extended Platform (Active Development)

4. tta-agent-coordination → platform/agent-coordination/

5. tta-dev-integrations → platform/integrations/

6. tta-documentation-primitives → platform/documentation/

7. tta-kb-automation → platform/kb-automation/

📱 Applications

tta-observability-ui → apps/observability-ui/

🚀 Quick Start

📚 Documentation

Additional Resources

🧪 Testing

🛠️ Development

Prerequisites

Setup

VS Code Workflow

PR Management

🤝 Contributing

Contribution Criteria

TODO Compliance Requirement

Contribution Workflow

📋 Code Quality Standards

Formatting

Linting

Type Checking

Testing

Documentation

🚦 CI/CD

📊 Project Status

Current Release: v0.1.0 (Initial)

Roadmap

🔗 Related Projects

📄 License

🙏 Acknowledgments

📧 Contact

⭐ Star History

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

1. `tta-dev-primitives` → `platform/primitives/`

2. `tta-observability-integration` → `platform/observability/`

3. `universal-agent-context` → `platform/agent-context/`

4. `tta-agent-coordination` → `platform/agent-coordination/`

5. `tta-dev-integrations` → `platform/integrations/`

6. `tta-documentation-primitives` → `platform/documentation/`

7. `tta-kb-automation` → `platform/kb-automation/`

`tta-observability-ui` → `apps/observability-ui/`

Packages