Synesis

The confluence of evidence into auditable knowledge.

A Domain-Specific Language and toolchain for transforming qualitative research annotations into structured, validated, and fully traceable knowledge artifacts.

Copyright (c) 2011–2026 Christian Maciel de Britto https://github.com/synesis-lang · ORCID

What is Synesis?

Qualitative research — literature reviews, grounded theory, case studies, systematic reviews — generates enormous interpretive work that is typically scattered across unstructured notes, spreadsheets, or proprietary software locked to a single vendor.

Synesis is a semantic compiler for analytical thinking: you write your interpretations in plain-text files with a clean declarative syntax, and the toolchain validates, structures, and exports them as canonical knowledge artifacts. Every concept is traceable to its source file, line, and column. No silent errors. No orphaned codes. No ambiguous relations.

The name comes from the Greek σύνεσις — the convergence of evidence fragments into an intelligible whole. In its biblical sense (Colossians 1:9, synesei pneumatikei), it denotes a form of understanding that connects rather than merely accumulates.

The core differentiator: validation happens at compile time, not at retrieval or graph construction. If a code does not exist in the declared ontology, the compiler rejects the annotation at the source — before any output is produced. This is the architectural distinction that separates Synesis from all known CAQDAS alternatives and RAG pipeline tooling.

The Ecosystem

📚 Zotero                    🤖 synesis-coder
   PDF annotations    ──►       AI-assisted annotation
   (zotero-synesis-export)       generates full .syn files
         │                              │
         ▼                              ▼
    📄 .syn / .synt / .syno / .synp  (Synesis source files)
         │
         ▼
    ⚙️  Synesis Compiler  (this package)
    LALR(1) parser · AST validator · multi-artifact exporter
         │
    ┌────┴──────────────────────────────────┐
    ▼                                       ▼
🐍 Python API                          📊 Structured outputs
   synesis.load()                         JSON · CSV · Excel
   to_dataframe()                         REFI-QDA · DOCX · Alpaca JSONL
         │                                       │
         ▼                                       ▼
📓 Jupyter Notebooks               🕸️  Neo4j / Memgraph
   data science · visualization        graph queries via MCP
         │
    🧠 synesis-lsp  ──►  🖥️  Synesis Explorer (VS Code)
       Language Server      real-time diagnostics · graph viewer

Installation

pip install synesis

Requires Python 3.10+.

A Complete Example

references.bib

@article{smith2024,
    author  = {Smith, Jane},
    title   = {Understanding Community Resilience},
    journal = {Journal of Social Research},
    year    = {2024},
    volume  = {12},
    pages   = {45--67}
}

template.synt — field schema and validation rules

SOURCE FIELDS
    OPTIONAL description
END SOURCE FIELDS

FIELD description TYPE TEXT
    SCOPE SOURCE
    DESCRIPTION General context or summary of the data source
    GUIDELINES
        Summarize the source purpose in 1-2 sentences.
        Do not add analytical interpretation.
    END GUIDELINES
END FIELD

ITEM FIELDS
    REQUIRED citation, note, code
END ITEM FIELDS

FIELD citation TYPE QUOTATION
    SCOPE ITEM
    DESCRIPTION Direct quote or selected excerpt from the data source
    GUIDELINES
        Extract a complete, self-contained excerpt of 1-3 sentences.
        Preserve the original wording. Do not paraphrase.
    END GUIDELINES
END FIELD

FIELD note TYPE MEMO
    SCOPE ITEM
    DESCRIPTION Analytical memo recording interpretations or causal reasoning
    GUIDELINES
        Explain the analytical significance in 1-3 sentences.
        Distinguish textual evidence from your interpretation.
    END GUIDELINES
END FIELD

FIELD code TYPE CODE
    SCOPE ITEM
    DESCRIPTION Ontology codes applied to this excerpt
    GUIDELINES
        Apply only codes supported by the excerpt.
        Every code must have a corresponding ONTOLOGY entry.
    END GUIDELINES
END FIELD

ONTOLOGY FIELDS
    REQUIRED definition, group
END ONTOLOGY FIELDS

FIELD definition TYPE TEXT
    SCOPE ONTOLOGY
    DESCRIPTION Clear definition of the code with inclusion/exclusion criteria
END FIELD

FIELD group TYPE TOPIC
    SCOPE ONTOLOGY
    DESCRIPTION Broader thematic domain that groups related codes
END FIELD

annotations.syn — your research data

SOURCE @smith2024
    description: Qualitative study on community resilience strategies in urban contexts.
END SOURCE

ITEM @smith2024
    citation: "People here look out for each other. When the flood came, nobody waited
        for official help — neighbors just organized themselves."

    note: Participant describes spontaneous collective action as a primary resilience
        mechanism, bypassing formal institutions. Suggests strong bonding social capital.

    code: Social_Cohesion, Collective_Action
END ITEM

ontology.syno — controlled vocabulary

ONTOLOGY Social_Cohesion
    definition: The degree to which community members trust, support, and cooperate
        with one another. Applies when participants describe solidarity or mutual aid.
    group: Community_Resilience
END ONTOLOGY

ONTOLOGY Collective_Action
    definition: Coordinated efforts by community members to address shared challenges
        without formal institutional direction.
    group: Community_Resilience
END ONTOLOGY

project.synp — the entry point

PROJECT demo
    TEMPLATE "template.synt"
    INCLUDE BIBLIOGRAPHY "references.bib"
    INCLUDE ANNOTATIONS "annotations.syn"
    INCLUDE ONTOLOGY    "ontology.syno"
END PROJECT

Every INCLUDE accepts a file, a glob or a folder, and several lines of the same type add up. A folder is searched recursively for the type's extension (.bib, .syn, .syno, .toml). This is how a large corpus is organized in batches:

PROJECT corpus
    TEMPLATE "template.synt"
    INCLUDE BIBLIOGRAPHY "Sources"              # one .bib per author
    INCLUDE ANNOTATIONS  "annotations_*/*.syn"  # one folder per coding run
    INCLUDE ONTOLOGY     "ontology.syno"
END PROJECT

The same key in two .bib files is an error (SYNESIS_E089).

CLI

# Compile a project and generate all output artifacts
synesis compile project.synp --output results/

# Validate syntax and integrity without generating output
synesis check annotations.syn

# Validate template structure and consistency
synesis validate-template template.synt

# Show version and authorship
synesis --version

# Show full intellectual genealogy
synesis --credits

Python API

Compile entirely in-memory — no file I/O required:

import synesis

result = synesis.load(
    project_content   = open("project.synp").read(),
    template_content  = open("template.synt").read(),
    annotation_contents = {"annotations.syn": open("annotations.syn").read()},
    ontology_contents   = {"ontology.syno": open("ontology.syno").read()},
    bibliography_content = open("references.bib").read(),
)

if result.success:
    # Export as pandas DataFrames
    items_df  = result.to_dataframe("items")
    codes_df  = result.to_dataframe("codes")
    chains_df = result.to_dataframe("chains")

    # Export as JSON
    data = result.to_json_dict()

    # Compilation stats
    print(result.stats)
    # CompilationStats(source_count=1, item_count=1, ontology_count=2, code_count=2)
else:
    for diagnostic in result.get_diagnostics():
        print(diagnostic)

Available tables: sources, items, ontologies, codes, chains.

Language Features

Sources & Items — Every annotation is traceable to a BibTeX reference. The compiler validates each @key against the bibliography at compile time.

Templates — Define field schemas with types (CODE, TEXT, CHAIN, SCALE, QUOTATION, MEMO...), validation rules (REQUIRED, OPTIONAL, FORBIDDEN), and constraints (ARITY, BUNDLE, VALUES). The template is the contract between the researcher and the compiler.

Ontologies — Controlled vocabularies validated at compile time. Every code must exist in the declared ontology — typos and orphaned concepts are caught immediately, at the source.

Chains — Causal or relational links: Trust -> ENABLES -> Acceptance. Validated against declared RELATIONS and ARITY constraints.

GUIDELINES — Instructional prose embedded in template field definitions, visible to human annotators and LLM coders, never parsed as code.

Deterministic multi-artifact emission — A single compilation pass produces JSON, CSV, Excel, REFI-QDA, DOCX, and Alpaca JSONL simultaneously. All-or-nothing: either every artifact is valid, or nothing is emitted.

File Types

Potential Applications

Architecture

synesis compile project.synp
         │
    Lark LALR(1) parser
         │
    AST Transformer
         │
    Semantic Validator ◄── ontology · bibliography · template contract
         │
    Exporters (single pass, all-or-nothing)
    ├── JSON
    ├── CSV
    ├── Excel
    ├── REFI-QDA
    ├── DOCX
    └── Alpaca JSONL  (fine-tuning datasets for open-weight LLMs)

The compiler exposes compile_string() for integration with synesis-lsp, enabling real-time diagnostics in the VS Code extension without spawning a subprocess.

VS Code Integration

The Synesis Explorer extension (requires synesis-lsp) provides:

• Real-time diagnostics — errors and warnings as you type
• Semantic syntax highlighting — AST-driven, not regex
• Tree explorers for References, Codes, Relations, and Ontology
• Go-to-definition, rename, and hover documentation
• Relation graph viewer (Mermaid → SVG)
• Abstract viewer with BibTeX highlights
• Synesis Dark and Light themes

Compatibility

Intellectual Genealogy

Synesis is the formal culmination of a research and development trajectory spanning more than a decade. Its architecture, domain vocabulary, and methodological requirements emerged from successive implementations across qualitative research, professional consultancy, and biblical hermeneutics:

All prior works are authored by Christian Maciel de Britto. The NOTICE file in the repository records the formal copyright notices for each predecessor work.

License

This program is distributed under the GNU Affero General Public License, version 3 only (AGPL-3.0-only), with the Synesis Data-Output Exception — see LICENSE and LICENSE.exception.

SPDX identifier: AGPL-3.0-only AND LicenseRef-Synesis-data-output-exception

Your research data and compiled outputs are yours. The files you feed to Synesis and the artifacts it produces from them — JSON, CSV, Excel, REFI-QDA, DOCX, Alpaca JSONL, and knowledge-graph exports — are not covered by the AGPL and carry no copyleft obligation toward Synesis. You may license and use those outputs however you wish. This holds even when an output carries Synesis's own runtime material, such as the JavaScript and CSS embedded in a generated graph visualization. See LICENSE.exception for the terms.

The AGPL applies to Synesis itself: if you modify Synesis and distribute it, or run it as a network service, you must share your changes under the AGPL.

Releases published before this change remain available under the MIT license they were issued under. This change does not affect any existing user's right to use outputs they have already compiled.

This license grants no rights to the "Synesis" name or logo.

Author

Dr. Christian Maciel de Britto Researcher · Software author · Knowledge engineer

GitHub · ORCID · Lattes

"True σύνεσις — the convergence of evidence fragments into an intelligible, auditable, and technically rigorous whole."