STL is a calculable, universal standard for structuring knowledge through directional semantic relations. It introduces a tension-path model where knowledge flows directionally from source to target, carrying semantic magnitude and type information.
Unlike JSON or plain text, STL statements are not just data — they are traceable, verifiable, and inference-ready.
[Theory_Relativity] -> [Prediction_TimeDilation] ::mod(
rule="logical",
confidence=0.99,
source="doi:10.1002/andp.19053221004",
author="Einstein"
)
- Human-readable yet machine-executable — Designed for both human comprehension and computational processing
- Traceable and verifiable — Every statement can embed provenance, confidence, and evidence
- Inference-friendly — Supports reasoning, verification, and knowledge graph construction
- Token-efficient — Compact syntax optimized for LLM context windows
- Unicode-native — Full support for Chinese, Arabic, and all Unicode scripts
A comprehensive Python toolkit for working with STL, with feature parity to the JSON ecosystem:
| Capability | Description |
|---|---|
| Parse & Serialize | parse(), to_json(), to_stl(), to_rdf() |
| Build Programmatically | stl("[A]", "[B]").mod(confidence=0.9).build() |
| Schema Validation | .stl.schema format + 6 domain schemas (TCM, medical, legal, ...) |
| LLM Output Repair | clean() + repair() + validate_llm_output() — 3-stage pipeline |
| Query & Filter | find(), filter(), select(), stl_pointer() — Django-style operators |
| Diff & Patch | stl_diff(), stl_patch() — semantic-level comparison |
| Streaming I/O | STLEmitter (write) + STLReader (read) + tail mode |
| Graph Analysis | NetworkX integration, cycle detection, centrality analysis |
| Confidence Decay | Time-based knowledge freshness with configurable half-life |
| CLI | stl validate, stl query, stl diff, stl patch, and more |
git clone https://github.com/scos-lab/semantic-tension-language.git
cd semantic-tension-language/parser
pip install -e .from stl_parser import parse, stl, stl_doc, validate_llm_output
# Parse STL text
result = parse('[Einstein] -> [Theory_Relativity] ::mod(confidence=0.98, rule="empirical")')
print(result.statements[0].source.name) # "Einstein"
# Build programmatically
stmt = stl("[Rain]", "[Flooding]").mod(confidence=0.85, rule="causal", strength=0.8).build()
print(str(stmt)) # [Rain] -> [Flooding] ::mod(confidence=0.85, ...)
# Clean LLM output
llm_result = validate_llm_output("A => B mod(confience=1.5)")
print(f"Valid: {llm_result.is_valid}, Repairs: {len(llm_result.repairs)}")stl validate input.stl # Validate
stl query input.stl --where "rule=causal" # Query
stl diff a.stl b.stl # Compare
stl patch a.stl diff.json # Apply patch- Getting Started — Installation, quickstart, key concepts
- Tutorials — Step-by-step guides for each capability
- API Reference — Complete API and CLI documentation
- How-To Guides — Task-oriented guides for common workflows
- Project Index — Module reference and architecture overview
- Tooling Features (Chinese) — Detailed feature overview
- Schema Ecosystem — Domain-specific schema library
- STL as LLM-Program Bridge — Vision document
semantic-tension-language/
├── spec/ # Language specifications (v1.0)
├── docs/ # Documentation library
│ ├── getting-started/ # Installation, quickstart, key concepts
│ ├── tutorials/ # Step-by-step learning guides
│ ├── reference/ # API reference and CLI docs
│ ├── guides/ # How-to guides
│ ├── schemas/ # Domain schema library (6 domains)
│ └── stlc/ # STLC semantic specifications (10 specs)
└── parser/ # Python package (stl-parser)
├── stl_parser/ # Source (19 modules)
└── tests/ # Test suite (530 tests, 88% coverage)
- Code: Apache License 2.0
- Specification: CC BY 4.0
STL is an open standard. We welcome issues, discussions, and contributions. See parser/CONTRIBUTING.md for guidelines.
Wuko. (2025). Semantic Tension Language (STL): A Theoretical Framework
for Structured and Interpretable Knowledge Representation (v1.0).
Zenodo. https://doi.org/10.5281/zenodo.17585432