Key Concepts

This guide explains the foundational concepts of Semantic Tension Language. After reading, you’ll understand anchors, paths, modifiers, and how STL differs from other data formats.

The Tension-Path Model

STL structures knowledge as directed statements where meaning flows from a source to a target:

[Source] -> [Target] ::mod(metadata)

This is called the tension-path model. Each statement represents a semantic relation — a piece of structured knowledge with direction, type, and provenance.

Think of it like this:

Together, a collection of STL statements forms a knowledge graph — traceable, verifiable, and machine-processable.

Anchors

An anchor is a node in the knowledge graph. It represents an entity, concept, event, or state.

Syntax

[AnchorName]
[Namespace:AnchorName]

Rules:

• Enclosed in square brackets [...]
• Names use alphanumeric characters, underscores, and Unicode letters
• No spaces, no special characters (except _ and :)
• Maximum 64 characters recommended

Naming Conventions

[Gravity]                    # Simple concept
[Theory_Relativity]          # Underscore separation
[UniversalGravitation]       # PascalCase
[Physics:Energy]             # Namespaced (disambiguates from Psychology:Energy)
[Event_2025_Summit]          # Dated event

Unicode Support

STL natively supports Chinese, Arabic, and all Unicode scripts:

[黄帝内经] -> [素问] ::mod(rule="definitional", confidence=0.95)

9 Anchor Types

STL defines 9 canonical anchor types across three layers:

Semantic Layer — abstract concepts and relations

Entity Layer — concrete objects and events

Structural Layer — meta-linguistic and reasoning

Anchor types are optional classifications — the parser accepts any valid anchor name regardless of type.

Paths (Arrows)

A path is the directional arrow connecting two anchors. Direction matters: [A] -> [B] is different from [B] -> [A].

Syntax

Two equivalent forms:

[A] -> [B]     # ASCII arrow
[A] → [B]      # Unicode arrow (U+2192)

Path Types

Paths carry implicit semantic meaning based on context:

Chained Paths

Multiple anchors can be chained in a single statement:

[Theory] -> [Experiment] -> [Observation] -> [Law]

This expands to three separate statements internally. Keep chains to 3-5 nodes maximum for readability.

Modifiers

Modifiers attach metadata to a statement. They carry provenance, confidence, temporal context, and other dimensions.

Syntax

[A] -> [B] ::mod(key=value, key=value, ...)

Rules:

• Always prefixed with ::
• Key-value pairs inside mod(...)
• String values are quoted: rule="causal"
• Numeric values are unquoted: confidence=0.85
• Comma-separated

Modifier Categories

STL defines 30+ standard modifier fields across 9 categories:

Logical (most important for knowledge graphs)

Provenance (required for verifiable knowledge)

Temporal

Causal

Spatial

Affective, Value, Cognitive, Mood

Additional categories for emotion (emotion, intensity, valence), value judgments (value, alignment, priority), cognitive framing (intent, focus, perspective), and mood (mood, modality).

See the Modifier Reference for the complete list.

Custom Modifiers

Any key not in the standard set is stored as a custom modifier:

[Drug_X] -> [Effect_Y] ::mod(
  confidence=0.85,
  dosage="500mg",
  trial_id="NCT12345678"
)

Here dosage and trial_id are custom fields — the parser preserves them as extra attributes accessible via getattr(stmt.modifiers, "dosage").

Confidence Calibration

Confidence scores should reflect genuine uncertainty, not default to 1.0:

Example:

# Definitional truth — very high confidence
[Water] -> [H2O] ::mod(rule="definitional", confidence=0.99)

# Strong empirical evidence
[Smoking] -> [Lung_Cancer] ::mod(rule="causal", confidence=0.92, strength=0.85)

# Speculative hypothesis
[Consciousness] -> [Quantum_Microtubules] ::mod(rule="causal", confidence=0.35)

How STL Differs from Other Formats

vs. JSON

JSON stores data. STL stores knowledge with provenance.

{"source": "Einstein", "target": "Relativity", "confidence": 0.98}

[Einstein] -> [Theory_Relativity] ::mod(confidence=0.98, source="doi:10.1002/andp.19053221004")

STL adds: directionality, typed relations, built-in provenance, confidence semantics, graph structure.

vs. RDF/Turtle

RDF represents triples (subject-predicate-object). STL represents tension paths with rich metadata.

:Einstein :developed :TheoryRelativity .

[Einstein] -> [Theory_Relativity] ::mod(
  rule="empirical", confidence=0.98,
  source="doi:10.1002/andp.19053221004", time="1905-09-26"
)

STL adds: human readability, first-class confidence, temporal context, LLM compatibility.

vs. OWL/Description Logic

OWL focuses on ontology (class hierarchies, logical axioms). STL focuses on knowledge statements with provenance and uncertainty. They are complementary — STL can feed into OWL ontologies via RDF serialization.

The Python Data Model

The parser maps STL syntax to Pydantic models:

from stl_parser import parse

result = parse('[A] -> [B] ::mod(confidence=0.9, rule="causal")')

# ParseResult
result.is_valid       # True
result.statements     # [Statement(...)]
result.errors         # []
result.warnings       # []

# Statement
stmt = result.statements[0]
stmt.source           # Anchor(name="A")
stmt.target           # Anchor(name="B")
stmt.modifiers        # Modifier(confidence=0.9, rule="causal")

# Anchor
stmt.source.name      # "A"
stmt.source.namespace  # None

# Modifier
stmt.modifiers.confidence  # 0.9
stmt.modifiers.rule        # "causal"
stmt.modifiers.custom      # {} (custom dict, used by builder)

What’s Next?

• Tutorials — Step-by-step guides for each capability
• API Reference — Complete function and class documentation
• STL Syntax Card — One-page quick reference