Metadata-Version: 2.4
Name: katalyst-taxonomy
Version: 1.3.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,export,graph-database,neo4j,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
Provides-Extra: export
Requires-Dist: asyncpg>=0.29; extra == 'export'
Requires-Dist: neo4j>=5.0; extra == 'export'
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.0; extra == 'neo4j'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
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 |
| **Graph Database Export** | Export taxonomy to Neo4j for visualization, impact analysis, and dependency queries (`kata tax export neo4j`) |
| **PostgreSQL Export** | Export taxonomy to PostgreSQL for SQL analytics, BI dashboards, and recursive CTE queries (`kata tax export postgres`) |
| **Unified Backend Protocol** | Pluggable storage backends (filesystem, Neo4j, PostgreSQL) with `kata tax sync` for multi-backend mirroring |
| **MCP Server** | Model Context Protocol server for AI assistant integration (30 tools, 6 resources, 3 prompts) |

---

## Storage Backends

Katalyst is designed to meet teams where they are. Not every team needs a database — many just need architecture-as-code in git.

### Filesystem (default, zero infrastructure)

Taxonomy nodes are **YAML files checked into git**. No database required. Every change is a commit, every review is a PR, and the taxonomy is readable directly on GitHub or GitLab. This is the recommended starting point and works for most teams.

```bash
pip install katalyst-taxonomy
kata tax init --yes
kata tax tree
```

### Neo4j (graph visualization, impact analysis)

When a taxonomy grows beyond what's easy to reason about in flat files, sync it to Neo4j for **interactive graph exploration**, impact analysis ("what breaks if I remove this stack?"), and cross-wing queries across 15 semantic relationship types.

```bash
pip install katalyst-taxonomy[neo4j]
kata tax export neo4j --full --uri neo4j://localhost:7687 --password secret --path .
```

### PostgreSQL (SQL analytics, BI integration)

For organizations that need taxonomy data in dashboards, reports, or backing an API layer. Standard SQL access, recursive CTEs for hierarchy queries, JSONB filtering on metadata, and compatibility with any BI tool.

```bash
pip install katalyst-taxonomy[postgres]
kata tax export postgres --dsn postgresql://user:pass@localhost:5432/katalyst --path .
```

### Using Multiple Backends Together

The filesystem stays the source of truth. Databases are synced mirrors. Edit YAML in git, sync periodically:

```bash
kata tax sync --full     # Push filesystem -> all configured backends
kata tax sync --target neo4j  # Sync to specific backend
```

---

## 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

# Graph Export
kata tax export neo4j                    # Incremental sync to Neo4j
kata tax export neo4j --full             # Full export (clear + recreate)
kata tax export neo4j --dry-run          # Preview what would be exported
kata tax export postgres                 # Export to PostgreSQL
kata tax export postgres --full          # Full export (truncate + recreate)
kata tax export postgres --dry-run       # Preview what would be exported

# Backend Sync
kata tax sync                            # Sync taxonomy to backend mirrors
kata tax sync --dry-run                  # Preview sync operations
kata tax sync --full                     # Full sync (clear + recreate)
```

---

## 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

pip install katalyst-taxonomy[neo4j]  # Enable Neo4j graph export
pip install katalyst-taxonomy[postgres]  # Enable PostgreSQL export
pip install katalyst-taxonomy[export]    # Enable all export backends

# 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)
