rdf-construct 0.3.0__tar.gz → 0.4.0__tar.gz

{rdf_construct-0.3.0 → rdf_construct-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rdf-construct
-Version: 0.3.0
+Version: 0.4.0
 Summary: Semantic RDF manipulation toolkit - order, serialize, and diff RDF ontologies
 License-Expression: MIT
 License-File: LICENSE
@@ -50,6 +50,7 @@ Description-Content-Type: text/markdown
 ## Features
 
 - **Semantic Ordering**: Serialise RDF/Turtle with intelligent ordering instead of alphabetical chaos
+- **Ontology Description**: Quick orientation to unfamiliar ontologies with profile detection
 - **Documentation Generation**: Create navigable HTML, Markdown, or JSON documentation from ontologies
 - **UML Generation**: Create PlantUML class diagrams from RDF ontologies
 - **PUML2RDF**: Convert PlantUML diagrams to RDF/OWL ontologies (diagram-first design)
@@ -64,6 +65,7 @@ Description-Content-Type: text/markdown
 - **Ontology Statistics**: Comprehensive metrics with comparison mode
 - **Flexible Styling**: Configure colours, layouts, and visual themes for diagrams
 - **Profile-Based**: Define multiple strategies in YAML configuration
+- **Multi-Format Input**: Supports Turtle, RDF/XML, JSON-LD, N-Triples
 - **Deterministic**: Same input + profile = same output, always
 
 ## Why?
@@ -93,6 +95,19 @@ pip install -e .
 poetry install
 ```
 
+### Describe an Ontology
+
+```bash
+# Quick orientation to an unfamiliar ontology
+rdf-construct describe ontology.ttl
+
+# Brief summary (metadata + metrics + profile)
+rdf-construct describe ontology.ttl --brief
+
+# JSON output for scripting
+rdf-construct describe ontology.ttl --format json
+```
+
 ### Compare Ontology Versions
 
 ```bash
@@ -243,15 +258,16 @@ rdf-construct localise report ontology.ttl --languages en,de,fr
 
 **For Users**:
 - [Getting Started](docs/user_guides/GETTING_STARTED.md) - 5-minute quick start
+- [Describe Guide](docs/user_guides/DESCRIBE_GUIDE.md) - Quick ontology orientation
 - [Docs Guide](docs/user_guides/DOCS_GUIDE.md) - Documentation generation
 - [UML Guide](docs/user_guides/UML_GUIDE.md) - Complete UML features
-- [PlantUML Import Guide](docs/user_guides/PLANTUML_IMPORT_GUIDE.md) - Diagram-first design
+- [PUML2RDF Guide](docs/user_guides/PUML2RDF_GUIDE.md) - Diagram-first design
 - [SHACL Guide](docs/user_guides/SHACL_GUIDE.md) - SHACL shape generation
 - [Diff Guide](docs/user_guides/DIFF_GUIDE.md) - Semantic ontology comparison
 - [Lint Guide](docs/user_guides/LINT_GUIDE.md) - Ontology quality checking
 - [CQ Testing Guide](docs/user_guides/CQ_TEST_GUIDE.md) - Competency question testing
 - [Stats Guide](docs/user_guides/STATS_GUIDE.md) - Ontology metrics
-- [Merge Guide](docs/user_guides/MERGE_GUIDE.md) - Combining ontologies
+- [Merge & Split Guide](docs/user_guides/MERGE_SPLIT_GUIDE.md) - Combining and modularising ontologies
 - [Refactor Guide](docs/user_guides/REFACTOR_GUIDE.md) - Renaming and deprecation
 - [Localise Guide](docs/user_guides/LOCALISE_GUIDE.md) - Multi-language translations
 - [CLI Reference](docs/user_guides/CLI_REFERENCE.md) - All commands and options
@@ -409,7 +425,7 @@ properties:
 
 ## Project Status
 
-**Current**: v0.2.0 - Feature complete for core ontology workflows  
+**Current**: v0.4.0 - Feature complete for core ontology workflows  
 **License**: MIT
 
 ### Implemented
@@ -425,10 +441,15 @@ properties:
 ✅ Ontology linting (11 rules)  
 ✅ Competency question testing  
 ✅ Ontology statistics  
+✅ Ontology merging and splitting  
+✅ Ontology refactoring (rename, deprecate)  
+✅ Multi-language translation management  
+✅ Ontology description and profile detection  
+✅ Multi-format input support (Turtle, RDF/XML, JSON-LD, N-Triples)  
 ✅ Comprehensive documentation
 
 ### (Possible) Roadmap
-- [ ] Multi-format input support (JSON-LD, RDF/XML)
+- [ ] OWL 2 named profile detection (EL, RL, QL)
 - [ ] Streaming mode for very large graphs
 - [ ] Web UI for diagram configuration
 - [ ] Additional lint rules
@@ -491,6 +512,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-**Status**: v0.2.0  
+**Status**: v0.4.0  
 **Python**: 3.10+ required  
 **Maintainer**: See [CONTRIBUTING.md](CONTRIBUTING.md)
+

{rdf_construct-0.3.0 → rdf_construct-0.4.0}/README.md

@@ -12,6 +12,7 @@
 ## Features
 
 - **Semantic Ordering**: Serialise RDF/Turtle with intelligent ordering instead of alphabetical chaos
+- **Ontology Description**: Quick orientation to unfamiliar ontologies with profile detection
 - **Documentation Generation**: Create navigable HTML, Markdown, or JSON documentation from ontologies
 - **UML Generation**: Create PlantUML class diagrams from RDF ontologies
 - **PUML2RDF**: Convert PlantUML diagrams to RDF/OWL ontologies (diagram-first design)
@@ -26,6 +27,7 @@
 - **Ontology Statistics**: Comprehensive metrics with comparison mode
 - **Flexible Styling**: Configure colours, layouts, and visual themes for diagrams
 - **Profile-Based**: Define multiple strategies in YAML configuration
+- **Multi-Format Input**: Supports Turtle, RDF/XML, JSON-LD, N-Triples
 - **Deterministic**: Same input + profile = same output, always
 
 ## Why?
@@ -55,6 +57,19 @@ pip install -e .
 poetry install
 ```
 
+### Describe an Ontology
+
+```bash
+# Quick orientation to an unfamiliar ontology
+rdf-construct describe ontology.ttl
+
+# Brief summary (metadata + metrics + profile)
+rdf-construct describe ontology.ttl --brief
+
+# JSON output for scripting
+rdf-construct describe ontology.ttl --format json
+```
+
 ### Compare Ontology Versions
 
 ```bash
@@ -205,15 +220,16 @@ rdf-construct localise report ontology.ttl --languages en,de,fr
 
 **For Users**:
 - [Getting Started](docs/user_guides/GETTING_STARTED.md) - 5-minute quick start
+- [Describe Guide](docs/user_guides/DESCRIBE_GUIDE.md) - Quick ontology orientation
 - [Docs Guide](docs/user_guides/DOCS_GUIDE.md) - Documentation generation
 - [UML Guide](docs/user_guides/UML_GUIDE.md) - Complete UML features
-- [PlantUML Import Guide](docs/user_guides/PLANTUML_IMPORT_GUIDE.md) - Diagram-first design
+- [PUML2RDF Guide](docs/user_guides/PUML2RDF_GUIDE.md) - Diagram-first design
 - [SHACL Guide](docs/user_guides/SHACL_GUIDE.md) - SHACL shape generation
 - [Diff Guide](docs/user_guides/DIFF_GUIDE.md) - Semantic ontology comparison
 - [Lint Guide](docs/user_guides/LINT_GUIDE.md) - Ontology quality checking
 - [CQ Testing Guide](docs/user_guides/CQ_TEST_GUIDE.md) - Competency question testing
 - [Stats Guide](docs/user_guides/STATS_GUIDE.md) - Ontology metrics
-- [Merge Guide](docs/user_guides/MERGE_GUIDE.md) - Combining ontologies
+- [Merge & Split Guide](docs/user_guides/MERGE_SPLIT_GUIDE.md) - Combining and modularising ontologies
 - [Refactor Guide](docs/user_guides/REFACTOR_GUIDE.md) - Renaming and deprecation
 - [Localise Guide](docs/user_guides/LOCALISE_GUIDE.md) - Multi-language translations
 - [CLI Reference](docs/user_guides/CLI_REFERENCE.md) - All commands and options
@@ -371,7 +387,7 @@ properties:
 
 ## Project Status
 
-**Current**: v0.2.0 - Feature complete for core ontology workflows  
+**Current**: v0.4.0 - Feature complete for core ontology workflows  
 **License**: MIT
 
 ### Implemented
@@ -387,10 +403,15 @@ properties:
 ✅ Ontology linting (11 rules)  
 ✅ Competency question testing  
 ✅ Ontology statistics  
+✅ Ontology merging and splitting  
+✅ Ontology refactoring (rename, deprecate)  
+✅ Multi-language translation management  
+✅ Ontology description and profile detection  
+✅ Multi-format input support (Turtle, RDF/XML, JSON-LD, N-Triples)  
 ✅ Comprehensive documentation
 
 ### (Possible) Roadmap
-- [ ] Multi-format input support (JSON-LD, RDF/XML)
+- [ ] OWL 2 named profile detection (EL, RL, QL)
 - [ ] Streaming mode for very large graphs
 - [ ] Web UI for diagram configuration
 - [ ] Additional lint rules
@@ -453,6 +474,6 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-**Status**: v0.2.0  
+**Status**: v0.4.0  
 **Python**: 3.10+ required  
-**Maintainer**: See [CONTRIBUTING.md](CONTRIBUTING.md)
+**Maintainer**: See [CONTRIBUTING.md](CONTRIBUTING.md)

{rdf_construct-0.3.0 → rdf_construct-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "rdf-construct"
-version = "0.3.0"
+version = "0.4.0"
 description = "Semantic RDF manipulation toolkit - order, serialize, and diff RDF ontologies"
 license = "MIT"
 readme = "README.md"

{rdf_construct-0.3.0 → rdf_construct-0.4.0}/src/rdf_construct/__init__.py

@@ -4,7 +4,7 @@ Named after the ROM construct from William Gibson's Neuromancer -
 preserved, structured knowledge that can be queried and transformed.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 from . import core, uml
 from .cli import cli

{rdf_construct-0.3.0 → rdf_construct-0.4.0}/src/rdf_construct/cli.py

@@ -1810,6 +1810,133 @@ def stats(
         sys.exit(1)
 
 
+@cli.command()
+@click.argument("file", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(path_type=Path),
+    help="Write output to file instead of stdout",
+)
+@click.option(
+    "--format",
+    "-f",
+    "output_format",
+    type=click.Choice(["text", "json", "markdown", "md"], case_sensitive=False),
+    default="text",
+    help="Output format (default: text)",
+)
+@click.option(
+    "--brief",
+    is_flag=True,
+    help="Show brief summary only (metadata, metrics, profile)",
+)
+@click.option(
+    "--no-resolve",
+    is_flag=True,
+    help="Skip import resolution checks",
+)
+@click.option(
+    "--reasoning",
+    is_flag=True,
+    help="Include reasoning analysis",
+)
+@click.option(
+    "--no-colour",
+    "--no-color",
+    is_flag=True,
+    help="Disable coloured output (text format only)",
+)
+def describe(
+    file: Path,
+    output: Path | None,
+    output_format: str,
+    brief: bool,
+    no_resolve: bool,
+    reasoning: bool,
+    no_colour: bool,
+):
+    """Describe an ontology: profile, metrics, imports, and structure.
+
+    Provides a comprehensive analysis of an RDF ontology file, including:
+    - Profile detection (RDF, RDFS, OWL DL, OWL Full)
+    - Basic metrics (classes, properties, individuals)
+    - Import analysis with optional resolvability checking
+    - Namespace categorisation
+    - Class hierarchy analysis
+    - Documentation coverage
+
+    FILE: RDF ontology file to describe (.ttl, .rdf, .owl, etc.)
+
+    \b
+    Examples:
+        # Basic description
+        rdf-construct describe ontology.ttl
+
+        # Brief summary only
+        rdf-construct describe ontology.ttl --brief
+
+        # JSON output for programmatic use
+        rdf-construct describe ontology.ttl --format json -o description.json
+
+        # Markdown for documentation
+        rdf-construct describe ontology.ttl --format markdown -o DESCRIPTION.md
+
+        # Skip slow import resolution
+        rdf-construct describe ontology.ttl --no-resolve
+
+    \b
+    Exit codes:
+        0 - Success
+        1 - Success with warnings (unresolvable imports, etc.)
+        2 - Error (file not found, parse error)
+    """
+    from rdf_construct.describe import describe_file, format_description
+
+    try:
+        click.echo(f"Analysing {file}...", err=True)
+
+        # Perform analysis
+        description = describe_file(
+            file,
+            brief=brief,
+            resolve_imports=not no_resolve,
+            include_reasoning=reasoning,
+        )
+
+        # Format output
+        use_colour = not no_colour and output_format == "text" and output is None
+        formatted = format_description(
+            description,
+            format_name=output_format,
+            use_colour=use_colour,
+        )
+
+        # Write output
+        if output:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(formatted)
+            click.secho(f"✓ Wrote description to {output}", fg="green", err=True)
+        else:
+            click.echo(formatted)
+
+        # Exit code based on warnings
+        if description.imports and description.imports.unresolvable_count > 0:
+            sys.exit(1)
+        else:
+            sys.exit(0)
+
+    except FileNotFoundError as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(2)
+    except ValueError as e:
+        click.secho(f"Error parsing RDF: {e}", fg="red", err=True)
+        sys.exit(2)
+    except Exception as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(2)
+
+
 @cli.command()
 @click.argument("sources", nargs=-1, type=click.Path(exists=True, path_type=Path))
 @click.option(

rdf_construct-0.4.0/src/rdf_construct/describe/__init__.py

@@ -0,0 +1,93 @@
+"""Describe command for RDF ontology analysis.
+
+Provides quick orientation and understanding of ontology files,
+answering: "What is this?", "How big is it?", "What does it depend on?",
+and "Can I work with it?"
+
+Usage:
+    from rdf_construct.describe import describe_file, format_description
+
+    description = describe_file(Path("ontology.ttl"))
+    print(format_description(description))
+
+    # Brief mode (metadata + metrics + profile only)
+    description = describe_file(Path("ontology.ttl"), brief=True)
+
+    # Skip import resolution (faster)
+    description = describe_file(Path("ontology.ttl"), resolve_imports=False)
+
+    # JSON output
+    print(format_description(description, format_name="json"))
+"""
+
+from rdf_construct.describe.models import (
+    OntologyDescription,
+    OntologyMetadata,
+    BasicMetrics,
+    ProfileDetection,
+    OntologyProfile,
+    NamespaceAnalysis,
+    NamespaceInfo,
+    NamespaceCategory,
+    ImportAnalysis,
+    ImportInfo,
+    ImportStatus,
+    HierarchyAnalysis,
+    DocumentationCoverage,
+    ReasoningAnalysis,
+)
+
+from rdf_construct.describe.analyzer import (
+    describe_ontology,
+    describe_file,
+)
+
+from rdf_construct.describe.formatters import (
+    format_description,
+    format_text,
+    format_markdown,
+    format_json,
+)
+
+from rdf_construct.describe.profiles import detect_profile
+from rdf_construct.describe.metrics import collect_metrics
+from rdf_construct.describe.imports import analyse_imports
+from rdf_construct.describe.namespaces import analyse_namespaces
+from rdf_construct.describe.hierarchy import analyse_hierarchy
+from rdf_construct.describe.documentation import analyse_documentation
+from rdf_construct.describe.metadata import extract_metadata
+
+
+__all__ = [
+    # Main functions
+    "describe_file",
+    "describe_ontology",
+    "format_description",
+    # Formatters
+    "format_text",
+    "format_markdown",
+    "format_json",
+    # Analysis functions (for direct use)
+    "detect_profile",
+    "collect_metrics",
+    "analyse_imports",
+    "analyse_namespaces",
+    "analyse_hierarchy",
+    "analyse_documentation",
+    "extract_metadata",
+    # Data models
+    "OntologyDescription",
+    "OntologyMetadata",
+    "BasicMetrics",
+    "ProfileDetection",
+    "OntologyProfile",
+    "NamespaceAnalysis",
+    "NamespaceInfo",
+    "NamespaceCategory",
+    "ImportAnalysis",
+    "ImportInfo",
+    "ImportStatus",
+    "HierarchyAnalysis",
+    "DocumentationCoverage",
+    "ReasoningAnalysis",
+]

rdf_construct-0.4.0/src/rdf_construct/describe/analyzer.py

@@ -0,0 +1,176 @@
+"""Main analyzer for ontology description.
+
+Orchestrates all analysis components and aggregates results into
+a complete OntologyDescription.
+"""
+
+from datetime import datetime
+from pathlib import Path
+
+from rdflib import Graph
+
+from rdf_construct.describe.models import OntologyDescription
+from rdf_construct.describe.metadata import extract_metadata
+from rdf_construct.describe.metrics import collect_metrics
+from rdf_construct.describe.profiles import detect_profile
+from rdf_construct.describe.namespaces import analyse_namespaces
+from rdf_construct.describe.imports import analyse_imports
+from rdf_construct.describe.hierarchy import analyse_hierarchy
+from rdf_construct.describe.documentation import analyse_documentation
+
+
+def describe_ontology(
+    graph: Graph,
+    source: str | Path,
+    brief: bool = False,
+    resolve_imports: bool = True,
+    include_reasoning: bool = False,
+) -> OntologyDescription:
+    """Generate a complete description of an ontology.
+
+    Runs all analysis components and aggregates results.
+
+    Args:
+        graph: Parsed RDF graph to analyse.
+        source: Source file path or identifier.
+        brief: If True, skip detailed analysis (imports, hierarchy, etc.).
+        resolve_imports: Whether to check resolvability of imports.
+        include_reasoning: Whether to include reasoning analysis.
+
+    Returns:
+        OntologyDescription with all analysis results.
+    """
+    # Always perform core analysis
+    metadata = extract_metadata(graph)
+    metrics = collect_metrics(graph)
+    profile = detect_profile(graph)
+
+    # Create base description
+    description = OntologyDescription(
+        source=source,
+        timestamp=datetime.now(),
+        metadata=metadata,
+        metrics=metrics,
+        profile=profile,
+        brief=brief,
+        include_reasoning=include_reasoning,
+    )
+
+    # Skip detailed analysis if brief mode
+    if brief:
+        return description
+
+    # Full analysis
+    description.namespaces = analyse_namespaces(graph)
+    description.imports = analyse_imports(graph, resolve=resolve_imports)
+    description.hierarchy = analyse_hierarchy(graph)
+    description.documentation = analyse_documentation(graph)
+
+    # Reasoning analysis is optional and off by default
+    if include_reasoning:
+        description.reasoning = _analyse_reasoning(graph, profile)
+
+    return description
+
+
+def describe_file(
+    file_path: Path,
+    brief: bool = False,
+    resolve_imports: bool = True,
+    include_reasoning: bool = False,
+) -> OntologyDescription:
+    """Generate a complete description of an ontology file.
+
+    Convenience function that handles file loading and format detection.
+
+    Args:
+        file_path: Path to RDF file.
+        brief: If True, skip detailed analysis.
+        resolve_imports: Whether to check resolvability of imports.
+        include_reasoning: Whether to include reasoning analysis.
+
+    Returns:
+        OntologyDescription with all analysis results.
+
+    Raises:
+        FileNotFoundError: If file does not exist.
+        ValueError: If file cannot be parsed.
+    """
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    # Detect format from extension
+    rdf_format = _infer_format(file_path)
+
+    # Parse the file
+    graph = Graph()
+    try:
+        graph.parse(str(file_path), format=rdf_format)
+    except Exception as e:
+        raise ValueError(f"Failed to parse {file_path}: {e}") from e
+
+    return describe_ontology(
+        graph=graph,
+        source=file_path,
+        brief=brief,
+        resolve_imports=resolve_imports,
+        include_reasoning=include_reasoning,
+    )
+
+
+def _infer_format(path: Path) -> str:
+    """Infer RDF format from file extension.
+
+    Args:
+        path: Path to RDF file.
+
+    Returns:
+        Format string for rdflib.
+    """
+    suffix = path.suffix.lower()
+    format_map = {
+        ".ttl": "turtle",
+        ".turtle": "turtle",
+        ".rdf": "xml",
+        ".xml": "xml",
+        ".owl": "xml",
+        ".nt": "nt",
+        ".ntriples": "nt",
+        ".n3": "n3",
+        ".jsonld": "json-ld",
+        ".json": "json-ld",
+    }
+    return format_map.get(suffix, "turtle")
+
+
+def _analyse_reasoning(graph: Graph, profile) -> "ReasoningAnalysis":
+    """Perform reasoning analysis (optional feature).
+
+    This is a placeholder for future reasoning analysis functionality.
+
+    Args:
+        graph: RDF graph to analyse.
+        profile: Detected profile.
+
+    Returns:
+        ReasoningAnalysis with reasoning implications.
+    """
+    from rdf_construct.describe.models import ReasoningAnalysis, OntologyProfile
+
+    # Determine entailment regime based on profile
+    regime_map = {
+        OntologyProfile.RDF: "none",
+        OntologyProfile.RDFS: "rdfs",
+        OntologyProfile.OWL_DL_SIMPLE: "owl-dl",
+        OntologyProfile.OWL_DL_EXPRESSIVE: "owl-dl",
+        OntologyProfile.OWL_FULL: "owl-full",
+    }
+
+    regime = regime_map.get(profile.profile, "unknown")
+
+    return ReasoningAnalysis(
+        entailment_regime=regime,
+        inferred_superclasses=[],
+        inferred_types=[],
+        consistency_notes=[],
+    )