Repository navigation
API Reference
Everything below is importable from noema unless a module path is shown.
import noemacompress(text, *, similarity_threshold=None, validation_threshold=0.75, token_model="cl100k_base", spacy_model="en_core_web_sm") -> CompressResult
Compress one text into notation with a round-trip confidence score. See Compressing Text.
CompressResult fields: notation, decoded_text, confidence, saved_percent,
original_tokens, notation_tokens.
Token count under a tiktoken encoding. Empty or whitespace-only text returns 0.
Render a SemanticGraph, or the sub-graph for entity_ids, as notation.
Parse notation into .entities (dict of local id to NotationEntity), .relations and
.events. Raises ValueError with a line number on malformed input.
Render notation as natural-language sentences. See Notation Format.
validate(original_text, decoded_text, threshold=0.75, model_name="all-MiniLM-L6-v2") -> ValidationResult
Embedding-similarity check. Result fields: confidence, passed, threshold.
noema.validator.nli.validate_nli(original_text, decoded_text, threshold=0.75, model_name="cross-encoder/nli-deberta-v3-base") -> NLIValidationResult
Entailment check. Result fields: confidence, passed, threshold, entailment, neutral,
contradiction. See Round-Trip Validation.
KnowledgeBase(embedding_model="all-MiniLM-L6-v2", similarity_threshold=0.85, spacy_model="en_core_web_sm")
| Method | Returns | Description |
|---|---|---|
ingest(documents) |
IngestReport |
Parse, canonicalize and merge a str, Document or list of either |
ingest_stream(documents, batch_size=100, checkpoint_path=None, on_batch=None) |
IngestReport |
Batched ingestion of any iterable |
retrieve(query, top_k=5, hops=1, max_tokens=200, format="notation", token_model="cl100k_base") |
RetrievalResult |
Hybrid retrieval |
save(path) |
None |
Write a .noema bundle |
KnowledgeBase.load(path) |
KnowledgeBase |
Read a bundle |
sync_to_backend(backend) |
None |
Replace a backend's contents with this graph |
KnowledgeBase.load_from_backend(backend, embedding_model=..., spacy_model=...) |
KnowledgeBase |
Read a backend into memory |
graph |
SemanticGraph |
The canonical graph (property) |
len(kb) |
int |
Number of graph nodes |
See Knowledge Bases, Retrieval and Large Datasets and Backends.
documents_ingested, entities_before, entities_after, entities_parsed, relations_before,
relations_after, and the property entities_merged.
| Field | Description |
|---|---|
text |
Context in the requested format |
notation |
Raw notation |
entity_ids, relation_ids
|
Sets of ids included |
token_count |
Tokens used |
truncated |
Whether the budget cut facts |
fact_matches |
List of FactMatch(relation_id, score)
|
An in-memory graph of entities, relations and events, built on networkx.
| Member | Description |
|---|---|
add_document(parsed), add_entity(e), add_relation(r), add_event(ev)
|
Add items. Relations and events need their entities added first |
get_entity(id), get_event(id)
|
Look up by id, or None
|
relations_of(entity_id) |
Relations touching an entity |
neighbors(entity_id, hops=1) |
Entities within hops edges, treating edges as undirected |
entities, relations, events
|
Lists of all items (properties) |
len(graph) |
Number of nodes |
| Type | Key fields |
|---|---|
Document |
id, text, metadata (dict of strings) |
Entity |
id, name, type (EntityType), aliases, mentions, confidence
|
Relation |
id, subject_id, predicate, object_id, mentions, confidence, valid_from, valid_to
|
Event |
id, label, participant_ids, time, mentions, confidence
|
SourceSpan |
doc_id, start_char, end_char, text
|
ParsedDocument |
document, entities, relations, events
|
EntityType |
PERSON, ORG, GPE, LOC, DATE, EVENT, PRODUCT, MONEY, OTHER
|
All are pydantic models, except EntityType, which is an enum.
| Function | Description |
|---|---|
extract_entities(document, model_name="en_core_web_sm") |
spaCy named entity recognition |
extract_relations(document, entities, model_name="en_core_web_sm") |
Rule-based relations for the same document |
canonicalize_entities(graph, ...) |
Merge duplicate entities in a graph. Accepts similarity_threshold and model_name
|
noema.parser.coref.resolve_coreferences(document) |
Coreference rewrite. See Advanced NLP |
noema.parser.transformer_relations.extract_relations_transformer(...), extract_relations_hybrid(...)
|
Transformer relations |
| Name | Description |
|---|---|
save_bundle(path, graph, model_name="all-MiniLM-L6-v2", spacy_model=None) |
Write a graph as a bundle |
load_bundle(path) |
Returns a LoadedBundle with graph, fact_ids, embeddings, index, manifest
|
GraphBackend |
Abstract backend interface |
noema.storage.neo4j_backend.Neo4jBackend(uri, auth=None, database="neo4j") |
Neo4j store |
noema.storage.rdf_backend.RDFBackend(path=None, format="turtle") |
RDF store |
| Name | Description |
|---|---|
noema.integrations.langchain.NoemaRetriever |
LangChain retriever |
noema.integrations.llamaindex.NoemaLlamaIndexRetriever |
LlamaIndex retriever |
noema.integrations.tokens.count_tokens_openai(text, model="gpt-4o") |
OpenAI token count |
noema.integrations.tokens.count_tokens_anthropic(text, model="claude-sonnet-5", api_key=None) |
Claude token count |
See Integrations.