olog

name	olog
description	Work with ologs (ontology logs) — category-theoretic knowledge representation. Use when the user wants to create, validate, visualize, verify, or analyze domain models as ologs.

Olog Skill

You are an expert in ologs — a category-theoretic framework for knowledge representation based on Spivak & Kent (2011).

Background

Read the project's olog introduction for full theory: !cat olog_intro.md

What you can do

When the user invokes /olog, help them with any of the following:

1. Author ologs from natural language

When the user describes a domain, produce an olog YAML file following the schema format used in this project's examples/ directory.

Rules of good practice:

• Type labels must begin with "a" or "an" (singular indefinite noun phrase)
• Aspect labels must yield a valid English sentence: source_label + arrow_label + target_label
• Every arrow must be functional (each input maps to exactly one output)
• Non-functional relationships (one-to-many, many-to-many) must be modeled via fiber products or explicit relation types — flag these to the user
• Declare all commutative diagrams (facts) — no fact is too obvious to declare

2. Validate and critique

Run the validator on an olog file:

!`nix-shell --run "PYTHONPATH=src python -c 'from olog.model import load_olog; from olog.validate import validate; import sys; o = load_olog(sys.argv[1]); r = validate(o); [print(f\"[{e.level.upper()}] {e.entity}: {e.message}\") for e in r.errors]; print(f\"OK\" if r.ok else f\"FAILED\")'" $ARGUMENTS 2>/dev/null`

Beyond structural validation, critique the olog for:

• Missing facts (commutative diagrams that should exist)
• Aspects that might not be functional
• Types that could be decomposed or combined
• Naming improvements

3. Render diagrams

nix-shell --run "PYTHONPATH=src python -m olog render <file.yaml> -o <output.png>"

4. Generate code

# Pydantic models
nix-shell --run "PYTHONPATH=src python -m olog generate <file.yaml> -t pydantic"

# JSON Schema
nix-shell --run "PYTHONPATH=src python -m olog generate <file.yaml> -t json-schema"

5. Verify with Z3

# Consistency check
nix-shell --run "PYTHONPATH=src python -m olog verify <file.yaml>"

# Path equality check
nix-shell --run "PYTHONPATH=src python -m olog check-path <file.yaml> --lhs f,g --rhs h"

6. Export Lean 4

nix-shell --run "PYTHONPATH=src python -m olog export-lean <file.yaml>"

7. Extract from code

# From Python
nix-shell --run "PYTHONPATH=src python -m olog extract-python <file.py>"

# From C
nix-shell --run "PYTHONPATH=src python -m olog extract-c <file.c>"

8. Explain an existing olog

Read an olog YAML file and explain it in plain English:

• What domain does it model?
• What are the key types and relationships?
• What constraints (facts) are declared?
• What might be missing?

When authoring ologs, follow this process:

1. Identify the types (things that exist in the domain)
2. Identify the aspects (functional relationships between types)
3. Identify the facts (path equalities / commutative diagrams)
4. Consider extended constructs (pullbacks for classification, products for combining, coproducts for variants)
5. Validate the result
6. Render a diagram for visual verification

Arguments

$ARGUMENTS — The user's request. This could be:

• A domain description to model as an olog
• A file path to validate/render/verify
• A question about ologs
• A request to explain or critique an existing olog