Capabilities

Overview

A capability is an operation that can be performed on files or content. Extract text from a PDF. Generate a thumbnail. Parse EPUB structure. Each capability has a unique identifier (a URN) that describes what it does.

How FileGrind uses capabilities

1. When you add a file, FileGrind checks what capabilities can handle it
2. It matches the file type to available capabilities (from plugins)
3. The most specific matching capability is selected
4. FileGrind calls the plugin that provides the capability
5. Results become chips in your library

CAPNS

FileGrind uses CAPNS (Capability Namespace System) for capability identification. CAPNS provides:

• A URN format for naming capabilities
• A matching algorithm for finding capabilities
• Specificity rules for choosing between multiple matches
• A public registry of capability definitions

Capability URNs

Each capability has a URN (Uniform Resource Name) built from key-value tags. Tags describe what the capability does.

Format

cap:key1=value1;key2=value2;key3=value3

Common tags

Examples

# Extract metadata from PDFs
cap:op=extract;format=pdf;target=metadata

# Extract text content from EPUBs
cap:op=extract;format=epub;target=pages

# Generate thumbnail from any document
cap:op=generate;target=thumbnail

# Translate to Spanish
cap:op=translate;language=es

Tag rules

• Tags are separated by semicolons
• Keys and values are case-insensitive (normalized to lowercase)
• Order doesn't matter (tags are sorted alphabetically)
• Values with special characters must be quoted
• Use * as a wildcard value

Matching

When FileGrind needs a capability, it searches available capabilities for matches. A capability matches a request if it can handle it.

Matching rules

1. If the request has a tag, the capability must either:
   • Have the same tag with the same value
   • Have the same tag with * (wildcard)
   • Not have that tag (acts as implicit wildcard)
2. The capability can have additional tags not in the request

Example

# Request: cap:op=extract;format=pdf

# These capabilities match:
cap:op=extract;format=pdf;target=metadata   # more specific
cap:op=extract;format=pdf                    # exact match
cap:op=extract;format=*                      # wildcard format
cap:op=extract                               # missing format = wildcard

# These do NOT match:
cap:op=extract;format=epub                   # wrong format
cap:op=generate;format=pdf                   # wrong action

Missing tags

A missing tag acts as a wildcard. A capability with fewer tags can handle more requests, but is less specific.

# Capability: cap:op=extract
# Matches any extraction request, regardless of format or target

# Capability: cap:op=extract;format=pdf
# Only matches PDF extraction requests

Specificity

When multiple capabilities match a request, FileGrind chooses the most specific one.

Calculation

Specificity = number of tags that match exactly (not wildcards). Higher specificity wins.

# Request: cap:op=extract;format=pdf;target=metadata

# Available capabilities:
cap:op=extract                              # specificity: 1
cap:op=extract;format=pdf                   # specificity: 2
cap:op=extract;format=pdf;target=metadata   # specificity: 3 (selected)
cap:op=extract;format=*;target=metadata     # specificity: 2 (* doesn't count)

Tie-breaking

If two capabilities have the same specificity:

1. Prefer the one with fewer total tags (more focused)
2. If still tied, alphabetical order by URN

Why specificity matters

Specificity allows general-purpose and specialized capabilities to coexist. A general PDF extractor handles all PDFs. A specialized extractor for a specific PDF type handles those better.

Standard Capabilities

FileGrind defines standard capabilities that all file-processing plugins should implement where applicable.

extract-metadata

Extract document metadata (title, author, page count, etc.)

URN: cap:op=extract;format={format};target=metadata
Input: File path
Output: FileMetadata JSON

extract-outline

Extract table of contents / document structure

URN: cap:op=extract;format={format};target=outline
Input: File path
Output: DocumentOutline JSON

grind

Extract text content organized by page

URN: cap:op=extract;format={format};target=pages
Input: File path, optional page range
Output: GroundChips JSON

generate-thumbnail

Generate preview image

URN: cap:op=generate;format={format};target=thumbnail
Input: File path, dimensions, page number
Output: PNG image data

Custom capabilities

Plugins can define additional capabilities beyond the standard set. Use descriptive tags that follow the existing patterns.

# Custom: extract specific data
cap:op=extract;format=xyz;target=annotations

# Custom: convert format
cap:op=convert;format=xyz;output=pdf

# Custom: analyze content
cap:op=analyze;format=xyz;target=sentiment

Arguments

Capabilities define what arguments they accept. Arguments have types, validation rules, and can be required or optional.

Argument definition

{
  "name": "file_path",
  "media_spec": "std:str.v1",
  "arg_description": "Path to input file",
  "cli_flag": "file_path",
  "position": 0,
  "validation": {
    "min_length": 1
  }
}

Argument types (media_spec)

Validation

{
  "validation": {
    "min": 0,              // Minimum value (numeric)
    "max": 100,            // Maximum value (numeric)
    "min_length": 1,       // Minimum length (string/array)
    "max_length": 255,     // Maximum length (string/array)
    "pattern": "^[a-z]+$", // Regex pattern (string)
    "allowed_values": ["a", "b", "c"]  // Enum values
  }
}

Positional vs flag arguments

# Positional (position field set)
./plugin extract-metadata /path/to/file.pdf
                          ^^^^^^^^^^^^^^^^^
                          position: 0

# Flag (cli_flag field set)
./plugin extract-metadata /path/to/file.pdf --output out.json
                                            ^^^^^^^^ ^^^^^^^^
                                            cli_flag: --output

Output

Capabilities define what output they produce. This helps FileGrind know how to process the result.

Output definition

{
  "output": {
    "media_spec": "std:obj.v1",
    "output_description": "Extracted metadata as JSON object"
  }
}

Output types

Handling output

JSON output goes to stdout and is parsed by FileGrind. Binary output (like thumbnails) can go to stdout or to a file specified by --output.

Capability Routing

FileGrind maintains a registry of all available capabilities from installed plugins. When an operation is needed, it routes to the appropriate plugin.

Discovery

1. At startup, FileGrind scans plugin directories
2. For each plugin, it runs plugin manifest
3. Parses the manifest to get capability definitions
4. Registers each capability with the router

Routing flow

1. FileGrind needs to extract metadata from a PDF
2. It builds a request: cap:op=extract;format=pdf;target=metadata
3. The router finds all matching capabilities
4. It selects the most specific match
5. FileGrind calls the plugin that provides that capability

Multiple plugins for same capability

If multiple plugins provide the same capability, the more specific one is preferred. If specificity is equal, the first registered plugin wins.

This allows specialized plugins to override general ones for specific file types or use cases.