← Skillful-Alhazen

Schema Reference

Schema Reference

The core schema is defined in local_resources/typedb/alhazen_notebook.tql. Skill namespace schemas live in local_skills/<skill>/schema.tql. Run make docs-schema-wiki to regenerate detailed per-namespace documentation (requires TypeDB running).

TypeDB 3.x Syntax Notes

This schema uses TypeDB 3.x syntax (3.8.0+). Key differences from 2.x:

Feature TypeDB 3.x TypeDB 2.x (old)
Attribute definition attribute x, value string; x sub attribute, value string;
Integer type value integer value long
Entity definition entity x sub y, (requires entity keyword) x sub y,
Relation definition relation x, x sub relation,
Abstract annotation entity x @abstract, sub y, x sub y @abstract,
Fetch syntax fetch { "key": $var.attr }; fetch $var: attr1, attr2;
Transactions driver.transaction(db, Type) driver.session(...).transaction(...)

Core Schema Hierarchy

All entities in the Alhazen system inherit from identifiable-entity. The hierarchy has three branches:

identifiable-entity (abstract)
├── domain-thing                      — real-world objects you reason about
│   ├── agent                         — AI agents and human actors
│   │   └── author                    — publication authors
│   └── [namespace types]             — one or more types per skill
│       scilit-paper, jobhunt-position, tech-recon-system, ...
├── collection                        — typed sets of domain objects
│   └── [namespace types]             — per-skill collection types
│       scilit-corpus, jobhunt-search, tech-recon-investigation, ...
└── information-content-entity (abstract) — content-bearing entities
    ├── artifact                      — raw captured content (HTML, PDF, API response)
    ├── fragment                      — extracted piece of an artifact
    └── note                          — agent analysis or annotation

Additional root entities (not in the main hierarchy):

  • organization — affiliations and institutions
  • information-resource — databases, knowledgebases, APIs
  • user-question — questions/instructions from users
  • vocabulary / vocabulary-type / vocabulary-property — external classification systems
  • tag — lightweight classification labels

Core Attributes

Identity and Naming

Attribute Type Description
id string (key) UUID — inherited by all identifiable-entity subtypes
name string Human-readable name
description string Longer text description
iri string URI/IRI identifier (for linked data)
abstract-text string Abstract or summary text

Content and Cache

Attribute Type Description
content string Inline content (< 50 KB)
content-hash string SHA hash for deduplication
format string MIME type or format string
token-count integer Token count for LLM context sizing
cache-path string Relative path in ~/.alhazen/cache/ (for ≥ 50 KB content)
mime-type string MIME type of cached file
file-size integer Size in bytes

Temporal

Attribute Type Description
created-at datetime Creation timestamp
updated-at datetime Last modified timestamp
publication-date datetime Date of publication
valid-from / valid-until datetime Validity window (affiliations, etc.)

Provenance

Attribute Type Description
provenance string Source description or URL
source-uri string Original source URI
confidence double Confidence score (0.0–1.0)
license string Content license

Core Relations

Knowledge Model

Relation Roles Purpose
aboutness note, subject Links notes to any identifiable-entity
representation artifact, referent Links artifacts to the things they represent
collection-membership collection, member Membership of entities in collections
collection-nesting parent-collection, child-collection Hierarchical collections
fragmentation whole, part Artifact → fragment relationship
derivation derivative, derived-from-source Provenance chain
note-threading parent-note, child-note Hierarchical note organization
citation-reference citing-item, cited-item Citation relationships
authorship author, work, publication-author Who created what
affiliation affiliated-agent, organization Agent membership in organizations

Classification System

Relation Roles Purpose
classification classified-entity, type-facet Assign vocabulary types to entities
tagging tagged-entity, tag Lightweight tagging
property-assertion subject-entity, property-definition Dynamic property assignment
semantic-triple triple-subject, triple-predicate, triple-object RDF-style assertions
evidence-chain claim, evidence Linking claims to supporting evidence

Skill Namespaces

Each skill extends the core schema with domain-specific types. All types use a namespace prefix to avoid collisions.

Namespace Prefix Skill Description
scilit- scientific-literature Papers, corpora, sources
jobhunt- jobhunt Positions, companies, skills, learning resources
tech-recon- tech-recon Systems, investigations, analyses
apt- alg-precision-therapeutics Diseases, genes, pathways, drugs
lit-trends- literature-trends Hypothesis threads and genealogies
tsw- they-said-whaaa Public figures, statements, claims
csb- curation-skill-builder Domain designs, phases, decisions

For detailed per-namespace schema, see each skill’s wiki page:

Design Conventions

Prefix everything. url is fine for a single-domain schema; jobhunt-url avoids collision when multiple skills share a database.

Reuse core attributes. Check the core schema before defining a new attribute — name, description, content, source-uri, created-at, confidence, license are already defined and inherited.

Domain objects are not information content. A paper, a gene, a job posting — these are domain-thing. The HTML page that describes the job posting is an artifact. The extracted salary requirement is a fragment. The fit analysis is a note.

Collections are typed per skill. Never use bare collection — define scilit-corpus sub collection so queries can target it specifically.

Relations before entities in namespace schemas. Define all relations first so role names resolve when entities use plays clauses.

No @key on custom attributes. Only the inherited id @key (from identifiable-entity) is permitted. Adding @key to namespace attributes causes schema errors.

See Also