CatSkill

A Category Theory-based AI Skill Orchestration Engine

CatSkill enables AI to understand "how skills collaborate" rather than just "which skills to call".

🎯 Core Value

Current Pain Points	CatSkill Solution
Skill composition relies on hardcoding	Automatic path discovery
Interface mismatches discovered at runtime	Compile-time type checking
Only forward execution	Supports backward reasoning
Multiple constraints handled manually	Automatic optimal solution finding
New domains require redevelopment	Declarative Schema integration

✨ Features

• Automatic Path Discovery: No manual orchestration needed, automatically finds all feasible skill combinations from A to B
• Compile-time Type Checking: Composition errors discovered during development, not at runtime
• Bidirectional Reasoning: Supports reverse inference from results to input conditions
• Multi-constraint Solving: Simultaneously satisfies multiple conditions, automatically finds optimal solutions
• Declarative Schema: New domain integration requires no code changes, just configuration

🚀 Quick Start

Installation

# Using uv (recommended)
uv pip install catskill

# Or using pip
pip install catskill

Basic Usage

1. Define your domain schema (YAML format):

# examples/weather.yaml
domains:
  - name: weather
    types:
      - name: Location
        description: "Geographic location"
      - name: Weather
        description: "Weather information"
    skills:
      - name: get_weather
        input: Location
        output: Weather
        types: [query]

2. Use CLI to validate and explore:

# Validate configuration
catskill validate examples/weather.yaml

# Find paths between types
catskill find-path Location Weather --config examples/weather.yaml

# Visualize skill graph
catskill graph --config examples/weather.yaml

# Reverse inference
catskill infer Weather --config examples/weather.yaml

Programmatic Usage

from catskill.schema import load_config
from catskill.engine import PathFinder

# Load configuration
registry = load_config("examples/weather.yaml").unwrap()

# Find paths
finder = PathFinder(registry)
paths = finder.find_paths(
    source=registry.get_object("Location"),
    target=registry.get_object("Weather")
)

for path in paths:
    print(f"Path: {path}")

📖 Documentation

• Product Requirements Document
• Contributing Guide
• Context & Status
• Design Decisions
• Roadmap

🏗️ Architecture

catskill/
├── core/        # Pure category theory abstractions
├── engine/      # Orchestration engine
├── adapters/    # Skill source adapters
├── schema/      # Domain schemas
├── cli/         # CLI tools
└── sdk/         # Public API

🧪 Testing

# Run tests
pytest

# With coverage
pytest --cov=catskill --cov-report=term-missing

📦 Project Status

• Version: v0.1.0
• Stage: Production (量产)
• Milestones:
  • ✅ M1: Core Engine (Skill registration, composition, path search)
  • ✅ M2: Advanced Capabilities (Constraint solving, bidirectional reasoning)
  • 🚧 M3: Verification (Consistency checking, information completion)
  • ⏳ M4: Adapters (MCP/Function Calling/Custom)
  • ⏳ M5: Toolchain (CLI, visualization)
  • ⏳ M6: Documentation & Examples

🛠️ Development

Prerequisites

• Python >= 3.10
• uv (recommended) or pip
• Git >= 2.0

Environment Setup

Git Configuration

# Set local git user email
git config --local user.email "ocarina1024@gmail.com"
git config --local user.name "ocarina1024"

Environment Variables

For GitHub API access and other integrations, set the following environment variable:

Windows (PowerShell):

# Set for current session
$env:GITHUB_TOKEN="your_github_token_here"

# Set permanently for user
[System.Environment]::SetEnvironmentVariable('GITHUB_TOKEN', 'your_github_token_here', 'User')

Linux/macOS:

# Set for current session
export GITHUB_TOKEN="your_github_token_here"

# Set permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export GITHUB_TOKEN="your_github_token_here"' >> ~/.bashrc

Setup

# Clone repository
git clone https://github.com/ocarina1024/Category.git
cd Category

# Install dependencies
uv pip install -e ".[dev]"

# Run tests
uvx pytest

Code Style

• Follow Google Python Style Guide
• Use type hints throughout
• Format with ruff
• Type check with mypy

Development Workflow

# Format code
uvx ruff format .

# Lint code
uvx ruff check .

# Type check
uvx mypy src/

# Run tests with coverage
uvx pytest --cov=catskill --cov-report=term-missing

# Build package
uvx nox -s build

📝 License

MIT License

🤝 Contributing

Please read CONTRIBUTING_AI.md for details on our collaboration protocol.

🔗 Links

• Repository: https://github.com/ocarina1024/Category
• Issues: https://github.com/ocarina1024/Category/issues

---

CatSkill - Making AI skill orchestration intelligent and composable.