Search API

SearchParameters

Structured representation of a search query, parsed from a natural language command string. Mirrors the Go SearchParameters struct.

decode_search_field(query::String) -> SearchParameters

Parse a natural language search query into structured SearchParameters.

Handles patterns like:

• "in chapter X" or "chapter X"
• "context Y" or "ctx Y"
• "arrows Z" or "arrow Z"
• "from X to Y"
• "range N" or "limit N" or "depth N"
• "forward" or "backward" (orientation/cone)
• "sequence about X" or "seq X"
• "notes on X"
• "about X" or "on X" or "for X"
• bare words are treated as search names

search_nodes(sst::SSTConnection, params::SearchParameters) -> Vector{Node}

Execute a structured search against the database, returning matching nodes.

search_text(sst::SSTConnection, text::String) -> Vector{Node}

Simple text search using TSVECTOR full-text search.

get_db_node_ptr_matching_nccs(sst::SSTConnection, name::String, chap::String,
                              context::Vector{String}, arrows::Vector{ArrowPtr},
                              seq::Bool, limit::Int) -> Vector{NodePtr}

Retrieve node pointers matching name/chapter/context/sequence constraints, ordered by text length (favouring exact matches) and cardinality.

decode_search_command(cmd::AbstractString; keywords::Vector{String}=SEARCH_KEYWORDS) -> SearchParameters

Parse a search command string into SearchParameters using segmented command parsing.

fill_in_parameters(cmd_parts::Vector{Vector{String}}, keywords::Vector{String}=SEARCH_KEYWORDS) -> SearchParameters

Parse segmented command parts into SearchParameters.

WeightedPath

A path through the graph with associated link weights.

weighted_search(store::MemoryStore, start::NodePtr;
                max_depth::Int=5, min_weight::Float32=0.0f0) -> Vector{WeightedPath}

Search paths from start where link weights affect ranking/filtering. Only follows links with weight ≥ min_weight. Returns all discovered paths up to max_depth hops.

dijkstra_path(store::MemoryStore, from::NodePtr, to::NodePtr) -> Union{WeightedPath, Nothing}

Find the shortest weighted path from from to to using Dijkstra's algorithm. Distance = 1/link.wgt so heavier weights = shorter distance. Links with zero weight are skipped.

rank_by_weight(paths::Vector{WeightedPath}; ascending::Bool=false) -> Vector{WeightedPath}

Sort paths by total weight. Default is descending (heaviest first).

infer_etc(node::Node) -> Etc

Infer Event/Thing/Concept classification from a node's link structure. Iterates over all ST channels and collapses the classification.

validate_etc(node::Node) -> Vector{String}

Return warnings about suspicious type assignments. Checks for inconsistencies between the node's ETC classification and its actual link structure.

collapse_psi(node::Node, stindex::Int) -> (Etc, String)

Collapse node classification along a specific ST dimension. Follows SST Gamma(3,4) inference rules from the Go implementation.

show_psi(etc::Etc) -> String

Display ETC classification as a comma-separated string. Matches the Go ShowPsi function output format.

validate_graph_types(store::MemoryStore) -> Dict{NodePtr, Vector{String}}

Validate all nodes in a graph. Returns a dictionary mapping node pointers to their validation warnings. Only nodes with warnings are included.

InhibitionContext

Represents include/exclude context filters for search. Nodes matching include but not exclude pass the filter.

parse_inhibition_context(query::String) -> InhibitionContext

Parse "context A,B NOT C,D" into include/exclude lists. The NOT keyword (case-insensitive) separates the include and exclude parts.

matches_inhibition(ctx_string::String, inhibition::InhibitionContext) -> Bool

Check if a context string matches the include list and doesn't match the exclude list. A context matches include if it contains all include terms. It fails if it contains any exclude term. Empty include list matches everything.

search_with_inhibition(store::MemoryStore, query::String,
                       inhibition::InhibitionContext) -> Vector{Node}

Search for nodes by text substring, filtering by inhibition context. A node passes if any of its link contexts match the inhibition filter, or if it has no links with context (uncontextualized nodes pass by default when include is empty).

ConeResult

Result of a causal cone search, containing all discovered paths from (or to) a root node, plus any identified supernodes.

forward_cone(store::MemoryStore, start::NodePtr;
             depth::Int=5, limit::Int=CAUSAL_CONE_MAXLIMIT) -> ConeResult

Traverse forward (positive-ST) links from start up to depth hops, collecting at most limit paths. Works entirely in memory.

forward_cone(sst::SSTConnection, start::NodePtr;
             depth::Int=5, limit::Int=CAUSAL_CONE_MAXLIMIT) -> ConeResult

Traverse forward links from start via the database stored function AllPathsAsLinks.

backward_cone(store::MemoryStore, start::NodePtr;
              depth::Int=5, limit::Int=CAUSAL_CONE_MAXLIMIT) -> ConeResult

Traverse backward (negative-ST) links to start up to depth hops.

backward_cone(sst::SSTConnection, start::NodePtr;
              depth::Int=5, limit::Int=CAUSAL_CONE_MAXLIMIT) -> ConeResult

Traverse backward links to start via the database.

entire_nc_cone(sst::SSTConnection, start_set::Vector{NodePtr};
               orientation::String="fwd", depth::Int=5,
               chapter::String="", context::Vector{String}=String[],
               limit::Int=CAUSAL_CONE_MAXLIMIT) -> ConeResult

Full name/chapter/context-filtered cone search via the database stored function AllNCPathsAsLinks.

select_stories_by_arrow(sst::SSTConnection,
                        nodeptrs::Vector{NodePtr},
                        arrowptrs::Vector{ArrowPtr},
                        sttypes::Vector{Int},
                        limit::Int) -> Vector{NodePtr}

Filter a set of node pointers to those whose links match the given arrow types and ST types. Mirrors the Go SelectStoriesByArrow.

select_stories_by_arrow(store::MemoryStore,
                        nodeptrs::Vector{NodePtr},
                        arrowptrs::Vector{ArrowPtr},
                        sttypes::Vector{Int},
                        limit::Int) -> Vector{NodePtr}

In-memory version: filter nodes to those present in the store.

get_fwd_paths_as_links(store::MemoryStore, start::NodePtr, sttype::Int,
                       depth::Int; limit::Int=100)

BFS expansion of forward cone, collecting complete paths as link vectors. Only follows links whose arrow belongs to the given signed sttype channel (positive ST values for forward). If sttype == 0, all positive channels are traversed.

Returns (paths::Vector{Vector{Link}}, count::Int).

get_entire_cone_paths_as_links(store::MemoryStore, orientation::String,
                               start::NodePtr, depth::Int; limit::Int=100)

Get cone paths as link vectors with orientation control. orientation is "fwd" (forward only), "bwd" (backward only), or "any" (both directions).

Returns (paths::Vector{Vector{Link}}, count::Int).

PathResult

Result of a path-finding operation between two nodes. paths contains DAG (loop-free) solutions. loops contains non-DAG paths that revisit nodes (loop corrections).

find_paths(store::MemoryStore, begin_node::NodePtr, end_node::NodePtr;
           chapter::String="", context::Vector{String}=String[],
           max_depth::Int=10) -> PathResult

Find all paths from begin_node to end_node in the in-memory graph, up to max_depth hops. Separates DAG paths from looped paths.

find_paths(sst::SSTConnection, begin_node::NodePtr, end_node::NodePtr;
           chapter::String="", context::Vector{String}=String[],
           max_depth::Int=10) -> PathResult

Find paths between two nodes using bidirectional cone expansion via the database. Mirrors the Go GetPathsAndSymmetries.

detect_path_loops(paths::Vector{Vector{NodePtr}}) -> Vector{Vector{NodePtr}}

Extract loops (repeated node subsequences) from a set of paths. Returns the subsequence of each path that forms a cycle.

UnifiedSearchParams

Parameters for a unified graph search combining text, context, weights, and structure.

unified_search(store::MemoryStore, params::UnifiedSearchParams) -> Vector{Node}

Perform a unified search combining text matching, chapter/context filtering, inhibition, and weight thresholds.

unified_search(store::MemoryStore, query::String; chapters=String[], max_results::Int=100) -> Vector{Node}

Convenience form: parse a natural language query like "fever NOT cold in:patients min_weight:0.5 st:leadsto".

Supported syntax:

• Plain text: substring match on node.s
• NOT term: exclude nodes whose name matches term
• in:chapter: restrict to chapter
• st:leadsto / st:contains / st:express / st:near: filter by ST type
• w>0.5: minimum weight on incident links

combinatorial_search(store::MemoryStore, terms::Vector{String}; mode::Symbol=:and) -> Vector{Vector{Node}}

Search for multiple terms simultaneously.

• :and — return a single vector containing nodes matching ALL terms
• :or — return a single vector containing nodes matching ANY term
• :product — return Cartesian product of matches for each term

cross_chapter_search(store::MemoryStore, query::String, chapters::Vector{String}) -> Dict{String, Vector{Node}}

Search for a query across multiple chapters, returning results grouped by chapter.

FocalView

A hierarchical view rooted at a node, traversing CONTAINS arrows.

focal_view(store::MemoryStore, root::NodePtr; depth::Int=1) -> FocalView

Build a hierarchical view from root by traversing CONTAINS arrows downward. Children are nodes that root contains (via positive CONTAINS arrows).

drill_down(store::MemoryStore, fv::FocalView, child::NodePtr) -> FocalView

Drill into a child node, making it the new focal root while preserving breadcrumb.

drill_up(store::MemoryStore, fv::FocalView) -> FocalView

Go up one level in the hierarchy using the breadcrumb trail.

tree_view(store::MemoryStore, root::NodePtr; max_depth::Int=3) -> String

Render a text tree view of the hierarchy from root.

hierarchy_roots(store::MemoryStore) -> Vector{NodePtr}

Find all nodes that contain other nodes but are not contained by any node. These are the top-level roots of the containment hierarchy.