Metadata-Version: 2.4
Name: katalyst-taxonomy
Version: 1.1.0
Summary: A taxonomy management system for software architecture
Project-URL: Homepage, https://github.com/esimplicityinc/katalyst-taxonomy
Project-URL: Repository, https://github.com/esimplicityinc/katalyst-taxonomy
Project-URL: Issues, https://github.com/esimplicityinc/katalyst-taxonomy/issues
Author: eSimplicity
License: Proprietary
License-File: LICENSE
Keywords: architecture,devops,platform-engineering,taxonomy
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: jsonschema>=4.22
Requires-Dist: loguru>=0.7
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: referencing>=0.35
Requires-Dist: rich>=13.0
Requires-Dist: sse-starlette>=2.0
Requires-Dist: textual>=0.89
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# Katalyst Taxonomy

**Define, organize, and manage your software architecture as code.**

Katalyst Taxonomy is a declarative framework for modeling your infrastructure and organization as a hierarchical tree. The **System Wing** organizes systems (which can nest), stacks, and layers; the **Org Wing** tracks organizations, programs, projects, teams, and team members. It brings structure to complex architectures, enabling consistent scaffolding, automated discovery, and seamless CI/CD integration.

---

## Why Katalyst?

Modern software architectures sprawl across hundreds of services, each with their own conventions, configurations, and tribal knowledge. Teams struggle with:

- **Inconsistent naming** - Every service structured differently
- **Lost knowledge** - New team members can't discover what exists
- **Manual scaffolding** - Copy-paste leads to drift and errors
- **Fragile automation** - CI/CD pipelines hardcode paths and assumptions

Katalyst solves these problems by providing a **single source of truth** for your architecture, expressed as simple YAML files that both humans and tools can understand.

[Learn more about why Katalyst](docs/users/why-katalyst.md)

---

## Key Features

| Feature | Description |
|---------|-------------|
| **Hierarchical Modeling** | Technical (System > Stack > Layer), Portfolio (Organization > Program > Project), and Organizational (Organization > Team > Team Member) hierarchies |
| **Declarative YAML** | Simple, version-controlled architecture definitions |
| **Schema Validation** | Catch errors early with JSON Schema validation |
| **Scaffolding Templates** | Generate consistent project structures from layer types |
| **Interactive TUI** | Browse and manage your taxonomy visually |
| **Environment-Aware** | First-class support for dev/staging/prod environments |
| **Extensible Plugins** | 57 bundled actions, 12 tools, 4 layer types — extend with your own |
| **Git Hook Integration** | Map kata actions to pre-commit, Husky, or Lefthook hooks |
| **AI Agents & Skills** | Bundled AI coding assistants with taxonomy-aware context |
| **MCP Server** | Model Context Protocol server for AI assistant integration (30 tools, 6 resources, 3 prompts) |

---

## Quick Start

### Install in Your Repository

```bash
# Install Katalyst (requires Python 3.12+)
pip install katalyst-taxonomy

# Initialize a new taxonomy in your repo
kata tax init --yes

# See what was created
kata tax tree
```

### Create Your First Architecture

```bash
# Create a system (root of your architecture)
kata tax create system my-platform \
  -d "My application platform" \
  -O team@example.com \
  -e dev -e prod

# Create a nested system (logical grouping)
kata tax create system backend \
  --parent my-platform \
  -d "Backend services" \
  -O backend@example.com \
  -e dev -e prod

# Create a stack (deployable component)
kata tax create stack api \
  --parent backend \
  -d "REST API service" \
  -O backend@example.com \
  -e dev -e prod

# Create a layer with scaffolding
kata tax create layer app \
  --parent api \
  --parent-system backend \
  --parent-system my-platform \
  --layer-type app-docker \
  -d "API application container" \
  -O backend@example.com \
  -e dev -e prod

# View your taxonomy
kata tax tree
```

Output:
```
my-platform [system]
 backend [system]
    api [stack]
       app [layer]
```

### Explore Interactively

```bash
# Launch the terminal UI
uv run python -m katalyst_taxonomy.tui

# Keyboard: arrows to navigate, 'n' to create, 'c' to clone, 'q' to quit
```

---

## Documentation

| Guide | Description |
|-------|-------------|
| [Why Katalyst](docs/users/why-katalyst.md) | Value proposition and use cases |
| [Getting Started](docs/users/getting-started.md) | Installation and first taxonomy |
| [Core Concepts](docs/users/core-concepts.md) | Hierarchy, FQTNs, environments |
| [CLI Reference](docs/users/cli-reference.md) | Complete command documentation |
| [TUI Guide](docs/users/tui-guide.md) | Interactive terminal interface |
| [Agents & Skills](docs/users/agents-guide.md) | AI coding assistants for your taxonomy |
| [Layer Types](docs/users/layer-types/index.md) | Built-in scaffolding templates |

### For Plugin Developers

| Guide | Description |
|-------|-------------|
| [Plugin Architecture](docs/extending/plugin-architecture.md) | How plugins work |
| [Creating Layer Types](docs/extending/creating-layer-types.md) | Custom scaffolding templates |
| [Creating Actions](docs/extending/creating-actions.md) | Executable layer commands |

### For Contributors

| Guide | Description |
|-------|-------------|
| [Contributing Guide](CONTRIBUTING.md) | How to contribute |
| [Architecture](docs/contributing/architecture.md) | Codebase design |
| [Development Setup](docs/contributing/development-setup.md) | Local environment |

---

## CLI Commands

```bash
# View commands
kata tax tree                    # Hierarchical tree view
kata tax list                    # Detailed list by type
kata tax json                    # Export as JSON
kata tax get <name>              # Get specific node

# Management
kata tax init                    # Initialize taxonomy in repo
kata tax create <type> <name>    # Create new node
kata tax add --layer-type <name> # Add layer type templates
kata tax remove --layer-type <n> # Remove layer type
kata tax upgrade                 # Upgrade installed components
kata tax upgrade --item <name>   # Upgrade a specific item

# Validation
kata tax lint                    # Validate against schemas
kata tax status                  # Show installed components

# AI Agents
kata tax agents init             # Initialize .agents/ and seed bundled agents/skills
kata tax agents list             # List agents and skills (local + bundled)
kata tax agents create <name>    # Create new agent
kata tax agents generate         # Generate from templates
kata tax agents sync             # Sync bundled content after upgrades
kata tax agents validate         # Validate definitions

# File Resolution
kata tax resolve --files <path>...  # Map files to layer FQTNs

# Git Hooks
kata tax hooks detect-tool           # Show configured hook tool
kata tax hooks generate --tool <t>   # Generate native hook config
kata tax hooks run                   # Run actions on affected layers
kata tax hooks validate              # Validate hook config
```

---

## Built-in Layer Types

| Type | Description |
|------|-------------|
| `app-docker` | Docker container application with multi-stage build |
| `k8s-kustomize` | Kubernetes manifests with Kustomize overlays |
| `k8s-argocd` | Argo CD application with GitOps workflow |
| `iac-terragrunt` | Terraform modules with Terragrunt wrapper |

Add more with `kata tax add --layer-type <name>` or create your own.

---

## Project Structure

After `kata tax init`, your repository will have:

```
your-repo/
 .global/
    taxonomy/
       taxonomy.lock    # Tracks installed components
       layer_types/           # Layer type templates
          app-docker/
          k8s-kustomize/
          ...
       actions/               # Action definitions + Just recipes
        extensions/            # Extension plugins
       capabilities/          # Capability declarations
       cicd/                  # CI/CD templates
 .agents/                        # AI agent definitions
    agents.yaml                 # Configuration
    agents/                     # Agent .md files
    skills/                     # Skill packages
 .taxignore                   # Paths to exclude from discovery
```

Your taxonomy nodes live alongside your code:

```
your-repo/
 system.yaml                  # System definition
 backend/
    system.yaml              # Nested system definition
    api/
       stack.yaml            # Stack definition
       app/
          layer.yaml         # Layer definition
          Dockerfile         # Scaffolded from layer type
          base/
          dev/
```

---

## Development

```bash
# Clone and install
git clone https://github.com/esimplicityinc/katalyst-taxonomy.git
cd katalyst-taxonomy
uv sync

# Run tests
uv run pytest

# Run linters
uv run ruff check
uv run pyright

# Run CLI
uv run kata --help

# Run TUI
uv run python -m katalyst_taxonomy.tui --path .

# Rebuild type registry (after editing node_types/)
uv run kata tax build-types
```

---

## License

[MIT License](LICENSE)

---

## Links

- [Documentation](docs/index.md)
- [GitHub Issues](https://github.com/esimplicityinc/katalyst-taxonomy/issues)
- [Schema Reference](schemas/README.md)
