### Install Hyperbase standalone with uv

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Install Hyperbase in a standalone environment using uv.

```bash
uv pip install hyperbase
```

--------------------------------

### Install Hyperbase from source with uv

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Clone the repository and install Hyperbase from source using uv.

```bash
git clone https://github.com/hyperbase/hyperbase.git
cd hyperbase
uv sync
```

--------------------------------

### Install Hyperbase from source with pip

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Clone the repository and install Hyperbase from source using pip.

```bash
git clone https://github.com/hyperbase/hyperbase.git
cd hyperbase
pip install .
```

--------------------------------

### Install Hyperbase with pip

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Use this command to install the Hyperbase package using pip.

```bash
pip install hyperbase
```

--------------------------------

### List installed Hyperbase parsers with uv

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

List installed Hyperbase parsers using the CLI within a uv environment.

```bash
uv run hyperbase parsers
```

--------------------------------

### Install spaCy English model with uv

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Download the English language model for spaCy using uv.

```bash
uv run python -m spacy download en_core_web_trf
```

--------------------------------

### List installed Hyperbase parsers

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Use the Hyperbase CLI to list all installed parser plugins.

```bash
hyperbase parsers
```

--------------------------------

### Install AlphaBeta parser with pip

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Install the AlphaBeta parser plugin for Hyperbase using pip.

```bash
pip install hyperbase-parser-ab
```

--------------------------------

### List Installed Parsers

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/parsers.md

Iterate through installed parsers and print their names and entry point values. This helps in identifying available parsing plugins.

```python
from hyperbase.parsers import list_parsers

for name, entry_point in list_parsers().items():
    print(f"{name}: {entry_point.value}")
```

--------------------------------

### Basic Hyperedge Example in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

This example demonstrates a simple hyperedge representing the sentence 'The sky is blue' using basic SH notation principles.

```sh
(is/P (the/M sky/C) blue/C)
```

--------------------------------

### Start Interactive Parsing REPL

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Launch the Hyperbase REPL for interactive parsing sessions. Use '/help' for available commands.

```bash
hyperbase repl --parser alphabeta --lang en
# Inside REPL: type sentences to parse, /help for commands
```

--------------------------------

### Start Hyperbase REPL with uv

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Launch the Hyperbase interactive REPL using uv, specifying the 'alphabeta' parser and 'en' language.

```bash
uv run hyperbase repl --parser alphabeta --lang en
```

--------------------------------

### Install spaCy English model

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Download the English language model for spaCy, required by the AlphaBeta parser.

```bash
python -m spacy download en_core_web_trf
```

--------------------------------

### Start Hyperbase REPL with AlphaBeta parser

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Launch the Hyperbase interactive REPL, specifying the 'alphabeta' parser and 'en' language.

```bash
hyperbase repl --parser alphabeta --lang en
```

--------------------------------

### Get and use a Hyperbase parser programmatically

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Demonstrates how to retrieve a parser instance programmatically and use it to parse text.

```python
from hyperbase import get_parser

parser = get_parser("alphabeta", lang="en")
results = parser.parse("The sky is blue.")
```

--------------------------------

### Registering Custom Parser as a Plugin

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/parsers.md

Example of registering a custom parser as a plugin in `pyproject.toml` for discoverability by `get_parser()`.

```toml
[project.entry-points."hyperbase.parsers"]
myparser = "my_package:MyParser"
```

--------------------------------

### Builder Hyperedge Example in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

Illustrates the 'builder' (B) hyperedge type, used to construct concepts from other concepts.

```sh
(of/B capital/C germany/C)
```

--------------------------------

### Import Hyperbase Hedge Function

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Import the necessary `hedge` function from the `hyperbase` library to start creating hyperedges.

```python
from hyperbase import hedge
```

--------------------------------

### Subtypes in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

Example demonstrating subtypes for predicate ('Pd'), modifier ('Md'), and concept ('Cc') hyperedges.

```sh
(is/Pd.sc (the/Md sky/Cc) blue/Cc)
```

--------------------------------

### Custom Parser Implementation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/parsers.md

Example of creating a custom parser by subclassing `Parser` and implementing required methods like `get_sentences` and `parse_sentence`.

```python
from hyperbase.parsers import Parser, ParseResult
from hyperbase.hyperedge import hedge

class MyParser(Parser):
    @classmethod
    def accepted_params(cls):
        return {
            "lang": {
                "type": str, "default": None,
                "description": "Language code.", "required": True,
            },
        }

    def __init__(self, params=None):
        super().__init__(params)
        self.lang = self.params["lang"]

    def get_sentences(self, text):
        # simple sentence splitting
        return [s.strip() for s in text.split(".") if s.strip()]

    def parse_sentence(self, sentence):
        edge = hedge(f"(says/P someone/C {sentence.split()[0]}/C)")
        return [ParseResult(
            edge=edge,
            text=sentence,
            tokens=sentence.split(),
            tok_pos=edge,
        )]
```

--------------------------------

### Predicate Hyperedge Example in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

Shows a 'predicate' (P) hyperedge used to build relations between concepts.

```sh
(is/P berlin/C nice/C)
```

--------------------------------

### Conjunction Hyperedge Example in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

Demonstrates the 'conjunction' (J) hyperedge type, used to define sequences of hyperedges.

```sh
(and/J meat/C potatoes/C)
```

--------------------------------

### Trigger Hyperedge Example in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

Shows the 'trigger' (T) hyperedge type, used to build specifications.

```sh
(in/T 1994/C)
```

--------------------------------

### Get a Parser Instance

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/parsers.md

Obtain a parser instance by its name and language code. Keyword arguments are forwarded to the parser constructor.

```python
from hyperbase import get_parser

parser = get_parser("alphabeta", lang="en")
```

--------------------------------

### Recursive Hyperedge Example

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/overview.md

Illustrates a hyperedge where a sub-hyperedge participates as a vertex. This demonstrates the recursive nature of Semantic Hypergraphs.

```plaintext
(a b c (d e f))
```

--------------------------------

### Predicate Argument Roles in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

Example showing argument roles 'subject' (s) and 'subject complement' (c) for a predicate hyperedge.

```sh
(is/P.sc (the/M sky/C) blue/C)
```

--------------------------------

### Modifier Hyperedge Example in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

Demonstrates the 'modifier' (M) hyperedge type, which can modify any other hyperedge type.

```sh
(red/M shoes/C)
```

--------------------------------

### Atomic Concept Example in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

Illustrates the 'concept' (C) hyperedge type, used to define atomic concepts.

```sh
apple/C
```

--------------------------------

### Focus Expansions on Relations with Two Arguments

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/discovering-patterns.md

Initialize PatternCounter with specific `expansions` to control which hyperedges are recursively expanded. This example focuses on relations with at least two arguments.

```python
pc = PatternCounter(expansions={" (*/P * * ...)"})
for edge in hg.all():
    if hg.is_primary(edge):
        pc.count(edge)
```

--------------------------------

### Get Reader Instance by Name

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/readers.md

When obtaining a reader instance using `get_reader`, you can specify the reader by name without needing to provide a source path initially.

```python
reader = get_reader(reader="wikipedia")
```

--------------------------------

### Get Most Common Patterns (Default)

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/discovering-patterns.md

Query the PatternCounter for the 10 most common patterns found in the hypergraph, including sub-structures.

```python
>>> pc.patterns.most_common(10)
[((*/M */C), 2208),
 ((*/J */C */C), 1867),
 ((*/B.ma */C */C), 1315),
 ((*/J */M */M), 708),
 ((*/J */P */P), 628),
 ((*/M (*/M */C)), 456),
 ((*/T */C), 448),
 ((*/B.ma (*/M */C) */C), 385),
 ((*/B.ma */C (*/M */C)), 315),
 ((*/B.mm */C */C), 266)]
```

--------------------------------

### Retrieve Argument Roles

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Demonstrates how to get the string representing the argument roles of a predicate in a hyperedge. The roles are encoded as letters following the predicate's type.

```python
>>> edge = hedge("(is/P.so paris/Cp nice/Cc)")
>>> edge.argroles()
'so'
```

--------------------------------

### Get All Atoms (with duplicates) from Hyperedge

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

The `all_atoms()` method returns a list of all atoms in a hyperedge, including duplicates. Use this when the frequency of atoms is important.

```python
>>> edge.all_atoms()
[the/Md, of/Br, mayor/Cc, the/Md, city/Cs]
```

--------------------------------

### Get Most Common Patterns (Focused Expansions)

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/discovering-patterns.md

Query the PatternCounter after setting specific expansion patterns to observe results focused on the defined criteria, such as relations with at least two arguments.

```python
>>> pc.patterns.most_common(10)
[((*/P.so */C */C), 146),
 ((*/P.sc */C */C), 92),
 ((*/P.sx */C */S), 65),
 ((*/P.sr */C */R), 57),
 ((*/P.sox */C */C */S), 54),
 ((*/P.px */C */S), 37),
 ((*/P.ox */C */S), 37),
 ((*/P.sr */C */S), 35),
 ((*/P.o? */C */R), 27),
 ((*/P.s? */C */R), 23)]
```

--------------------------------

### Get Hyperedge Size and Depth

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Measure the complexity of a hyperedge by its total number of atoms using `size()` and its deepest nesting level using `depth()`.

```python
edge = hedge("(is/P.so (the/Md sky/Cc) blue/Cc)")
>>> edge.size()
4
>>> edge.depth()
2
```

--------------------------------

### Count Concept Modifiers Including Subtypes

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/discovering-patterns.md

Utilize `match_subtypes` along with `match_roots` to include subtypes in pattern matching. This example discovers common concept modifiers with their subtypes.

```python
pc = PatternCounter(expansions={"(%/M %/C)"}, match_roots={"%%/M"}, match_subtypes={"%%/M"})
for edge in hg.all():
    if hg.is_primary(edge):
        pc.count(edge)
```

```pycon
>>> pc.patterns.most_common(10)
[((the/Md */C), 341),
 ((a/Md */C), 118),
 ((human/Ma */C), 53),
 ((artificial/Ma */C), 45),
 ((an/Md */C), 36),
 ((its/Mp */C), 25),
 ((other/Ma */C), 24),
 ((this/Md */C), 23),
 ((some/Md */C), 21),
 ((intelligent/Ma */C), 18)]
```

--------------------------------

### Get SH Notation String Representation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

Both `__str__` and `__repr__` methods return the hyperedge's string notation (SH notation). Printing a hyperedge directly displays this representation.

```python
>>> edge = hedge("(is/P.so berlin/Cp.s nice/Cc)")
>>> str(edge)
'(is/P.so berlin/Cp.s nice/Cc)'
```

--------------------------------

### Count Patterns with Explicit Roots

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/discovering-patterns.md

Use `match_roots` to include explicit atoms in patterns, useful for discovering actual predicates of common relations. This example counts primary edges matching patterns with explicit predicate roots.

```python
pc = PatternCounter(expansions={"(*/P * * ...)"}, match_roots={"%/P"})
for edge in hg.all():
    if hg.is_primary(edge):
        pc.count(edge)
```

```pycon
>>> pc.patterns.most_common(10)
[((is/P.sc */C */C), 27),
 ((are/P.sc */C */C), 17),
 ((has/P.so */C */C), 6),
 ((include/P.so */C */C), 6),
 ((have/P.so */C */C), 5),
 (((can/M be/P.sc) */C */C), 3),
 ((developed/P.so */C */C), 3),
 ((maximize/P.so */C */C), 3),
 ((perceives/P.so */C */C), 3),
 (((could/M spell/P.so) */C */C), 2)]
```

--------------------------------

### Builder Argument Roles in SH Notation

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/notation.md

Illustrates argument roles 'main concept' (m) and 'auxiliary concept' (a) for a builder hyperedge.

```sh
(of/B.ma founder/C psychoanalysis/C)
```

--------------------------------

### Initialize AlphaBeta Parser

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/parsing-a-sentence.md

Creates an AlphaBeta parser instance for the English language. Initialization may take time due to loading language models.

```python
from hyperbase import get_parser
parser = get_parser("alphabeta", lang="en")
```

--------------------------------

### Add Hyperbase to project with uv

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Add Hyperbase to your project's dependencies using the uv package manager.

```bash
uv add hyperbase
```

--------------------------------

### Parse Single Sentence Directly

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/parsers.md

Use `parse_sentence()` for a single sentence to get a list of `ParseResult` objects directly.

```python
results = parser.parse_sentence("The sky is blue.")
print(results[0].edge)
```

--------------------------------

### Generate Hypergraph Database

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/discovering-patterns.md

Use the command-line interface to parse a Wikipedia page and create a hypergraph database.

```bash
$ hyperbase --hg ai.db --url https://en.wikipedia.org/wiki/Artificial_intelligence wikipedia
```

--------------------------------

### Add AlphaBeta parser with uv

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Add the AlphaBeta parser plugin to your project dependencies using uv.

```bash
uv add hyperbase-parser-ab
```

--------------------------------

### Load Hyperedges from Various Sources

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Illustrates loading hyperedges using `load_edges()` from JSONL files, JSON files, text files, and iterables of strings or dictionaries. Supports lazy loading for large files.

```python
from hyperbase import load_edges, hedge

# Load from JSONL file (one ParseResult JSON per line)
edges = load_edges("output.jsonl")
for edge in edges:
    print(edge)

# Load lazily (returns generator for large files)
edges_gen = load_edges("large_file.jsonl", lazy=True)
for edge in edges_gen:
    print(edge)

# Load from JSON file (array of items)
edges = load_edges("edges.json")

# Load from text file (one edge string per line)
edges = load_edges("edges.txt")

# Load from iterable of strings
edge_strings = [
    "(is/P.sc berlin/C nice/C)",
    "(plays/P.so mary/C chess/C)",
]
edges = load_edges(edge_strings)
for edge in edges:
    print(edge)

# Load from iterable of dicts (treated as ParseResult)
data = [
    {"edge": "(is/P.sc sky/C blue/C)", "text": "The sky is blue.", "tokens": ["The", "sky", "is", "blue", "."], "tok_pos": "(0 (1 2) 3)"},
]
edges = load_edges(data)
for edge in edges:
    print(edge)
    print(edge.text)  # Text attribute preserved
```

--------------------------------

### Match Hyperedges with Patterns

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Demonstrates various ways to use the `edge.match()` method with different patterns, including no matches, boolean conditions, named variable capture, multiple variables, and wildcard matching.

```python
no_match = edge.match("(likes/P.so * *)")
print(no_match)  # []
```

```python
if edge.match("(plays/P.so * *)"):
    print("Pattern matched!")
```

```python
pattern_with_var = hedge("(plays/P.so PLAYER/C *)")
matches = edge.match(pattern_with_var)
print(matches)  # [{'PLAYER': mary/C}]
```

```python
pattern = hedge("(plays/P.so PLAYER/C GAME/C)")
matches = edge.match(pattern)
print(matches)  # [{'PLAYER': mary/C, 'GAME': chess/C}]
```

```python
edge2 = hedge("(is/P.so (my/Mp name/Cn) mary/Cp)")
print(edge2.match("(is/P.so . *NAME)"))  # [] - (my/Mp name/Cn) is not atomic
```

```python
print(edge2.match("(is/P.so (*) *NAME)"))  # [{'NAME': mary/Cp}]
```

```python
edge3 = hedge("(plays/P.sox alice/C chess/C (at/T (the/M club/C)))")
print(edge3.match("(plays/P * * ...)"))  # [{}] - matches with extra args
```

```python
pattern = hedge("(is/P.{sc} * */C)")
edge_a = hedge("(is/P.sc (the/M sky/C) blue/C)")
edge_b = hedge("(is/P.cs blue/C (the/M sky/C))")
print(edge_a.match(pattern))  # [{}] - matches
```

```python
print(edge_b.match(pattern))  # [{}] - also matches (order independent)
```

--------------------------------

### Get Inner Atom of Modifier Structure

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

The `inner_atom()` method extracts the inner atom from a modifier structure. For atoms, it returns the atom itself.

```python
>>> edge = hedge("(red/M shoes/C)")
>>> edge.inner_atom()
shoes/C
```

--------------------------------

### Create a Custom Hyperbase Parser

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Define a custom parser by extending the Parser base class and implementing parsing logic. Requires importing Parser, ParseResult, and hedge.

```python
from hyperbase.parsers import Parser, ParseResult
from hyperbase import hedge

class SimpleParser(Parser):
    @classmethod
    def accepted_params(cls):
        return {
            "lang": {
                "type": str,
                "default": "en",
                "description": "Language code.",
                "required": False,
            },
        }

    def __init__(self, params=None):
        super().__init__(params)
        self.lang = self.params.get("lang", "en")

    def get_sentences(self, text):
        # Simple sentence splitting on periods
        return [s.strip() for s in text.split(".") if s.strip()]

    def parse_sentence(self, sentence):
        # Simplified example - real parser would do NLP
        words = sentence.split()
        if len(words) >= 2:
            edge = hedge(f"(says/P.so someone/C {words[0].lower()}/C)")
        else:
            edge = hedge(f"({words[0].lower()}/C)")
        return [ParseResult(
            edge=edge,
            text=sentence,
            tokens=words,
            tok_pos=edge,
        )]

# Register in pyproject.toml:
# [project.entry-points."hyperbase.parsers"]
# simple = "my_package:SimpleParser"
```

--------------------------------

### Get All Subedges of a Hyperedge

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Retrieve a set of all subedges within a given hyperedge, including the edge itself, nested subedges, and individual atoms.

```python
edge = hedge("(is/P.so (the/Md sky/Cc) blue/Cc)")
>>> edge.subedges()
{(is/P.so (the/Md sky/Cc) blue/Cc), is/P.so, (the/Md sky/Cc), the/Md, sky/Cc, blue/Cc}
```

--------------------------------

### Get Most Common Patterns (No Sub-edges)

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/discovering-patterns.md

Query the PatternCounter after disabling sub-edge counting to see results dominated by conjunctions and relational constructs.

```python
>>> pc.patterns.most_common(10)
[((*/J */C */C), 1569),
 ((*/J */M */M), 708),
 ((*/J */P */P), 628),
 ((*/J */R */R), 131),
 ((*/J */T */T), 55),
 ((*/J */B */B), 30),
 ((*/B.mm */C */C), 29),
 ((*/J (*/J */R */R) */R), 29),
 ((*/P.so */C */C), 26),
 ((*/J */R */C), 24)]
```

--------------------------------

### CLI: Specify Reader and Parser

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/readers.md

When using the `hyperbase read` command, you can explicitly define the reader, parser, and language to use for processing the source.

```bash
# Specify reader and parser explicitly
hyperbase read source.txt -o output.jsonl --reader plain_text --parser alphabeta --lang en
```

--------------------------------

### Get Maximal Nesting Depth of Hyperedge

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

Determine the maximal nesting depth of a hyperedge using the `depth()` method. Atoms themselves have a depth of 0.

```python
>>> edge.depth()
3
>>> hedge("mary/C").depth()
0
```

--------------------------------

### Serialize and Reconstruct ParseResult Objects

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Demonstrates serializing ParseResult objects to JSON strings and dictionaries, and reconstructing them back into ParseResult objects. Also shows creating a hyperedge from a ParseResult.

```python
from hyperbase import get_parser, hedge
from hyperbase.parsers import ParseResult

parser = get_parser("alphabeta", lang="en")

# Parse and serialize
for result in parser.parse("The sky is blue."):
    # Serialize to JSON string
    json_str = result.to_json()
    print(json_str)

    # Serialize to dict
    d = result.to_dict()
    print(d)

    # Reconstruct from JSON
    restored = ParseResult.from_json(json_str)
    print(restored.edge)

    # Reconstruct from dict
    restored = ParseResult.from_dict(d)
    print(restored.edge)

# Create hyperedge with text attribute from ParseResult
for result in parser.parse("Mary plays chess."):
    edge = hedge(result)  # hedge() accepts ParseResult
    print(edge.text)      # "Mary plays chess."
```

--------------------------------

### Decode URL-Encoded Roots

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Use the `label()` method to get a human-readable version of an atom's root, automatically decoding URL-encoded characters.

```python
hedge("new%20york/Cp").label()
'new york'
```

--------------------------------

### Parse Sources from Files, URLs, and Wikipedia

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Shows how to parse content from local files, URLs, and Wikipedia articles using `parse_source()`. It also demonstrates writing parsed results to JSONL format and forcing a specific reader.

```python
from hyperbase import get_parser
from hyperbase.readers import get_reader, list_readers

parser = get_parser("alphabeta", lang="en")

# Parse from a local file
for results in parser.parse_source("article.txt"):
    for result in results:
        print(result.edge)
        print(result.source)  # {"source_type": "txt", "source": "article.txt"}

# Parse from a URL
for results in parser.parse_source("https://example.com/page.html"):
    for result in results:
        print(result.edge)

# Parse Wikipedia article directly
for results in parser.parse_source("https://en.wikipedia.org/wiki/Hypergraph"):
    for result in results:
        print(result.edge)
        print(result.source)  # {"source_type": "wikipedia", "source": "...", "title": "Hypergraph"}

# Write parsed results to JSONL
parser.parse_source_to_jsonl(
    "https://en.wikipedia.org/wiki/Alan_Turing",
    "turing.jsonl",
    progress=True
)

# Force a specific reader
for results in parser.parse_source(
    "https://en.wikipedia.org/wiki/Hypergraph",
    reader="url"  # Use generic URL reader instead of Wikipedia reader
):
    for result in results:
        print(result.edge)

# Use reader directly without parsing
reader = get_reader("article.txt")
for block in reader.read("article.txt"):
    print(block)  # Raw text blocks

# List available readers
for name, cls in list_readers().items():
    print(f"{name}: {cls.__name__}")
```

--------------------------------

### Get Connector Atom of Hyperedge

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

Retrieve the innermost connector atom by traversing modifier structures using `connector_atom()`. Returns `None` for simple atoms.

```python
>>> edge = hedge("(does/M (not/M like/P.so) john/C chess/C)")
>>> edge.connector_atom()
like/P.so
```

--------------------------------

### CLI: Parse Local File to JSONL

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/readers.md

Use the `hyperbase read` command to parse a local text file and output the results in JSONL format.

```bash
# Parse a local file to JSONL
hyperbase read article.txt -o output.jsonl
```

--------------------------------

### Create a Simple Atom

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Create a basic atomic hyperedge representing a single concept. The format is 'root/Type'.

```python
mary = hedge("mary/C")
>>> mary
mary/C
```

--------------------------------

### Nested Hyperedge: 'Mary climbs the highest mountain in Brazil'

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/overview.md

An example of arbitrarily nested hyperedges, combining propositions and concept modifiers to represent a complex sentence.

```plaintext
(climbs mary (the (highest (in mountain brazil))))
```

--------------------------------

### Run tests with uv and pytest

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Run project tests using pytest within a uv environment.

```bash
uv run pytest
```

--------------------------------

### Match hyperedges with specific types using wildcards in Python

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/patterns.md

Demonstrates matching hyperedges where specific types or subtypes are expected within the pattern, using wildcards like `*/C`.

```python
from hyperbase import hedge
pattern = hedge("(plays/P.so */C */C)")
edge = hedge("(plays/Pd.so alice/Cp chess/Cc)")
edge.match(pattern)  # returns [{}]
```

--------------------------------

### Get Unique Atoms from Hyperedge

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

Use the `atoms()` method to retrieve a set of unique atoms within a hyperedge. This is useful for understanding the distinct components of a hyperedge.

```python
>>> edge = hedge("(the/Md (of/Br mayor/Cc (the/Md city/Cs)))")
>>> edge.atoms()
{the/Md, of/Br, mayor/Cc, city/Cs}
```

--------------------------------

### Building Concepts: 'meat and potatoes'

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/overview.md

Demonstrates building a concept from other concepts using a connector. 'and' connects 'meat' and 'potatoes'.

```plaintext
(and meat potatoes)
```

--------------------------------

### Run tests with pytest

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/installation.md

Execute project tests using pytest from the project root.

```bash
pytest
```

--------------------------------

### Extract information using variables in Python

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/patterns.md

Define patterns with variables (atoms starting with an uppercase letter) to extract matched parts of a hyperedge. The results are returned in a list of dictionaries.

```python
from hyperbase import hedge
pattern = hedge("(plays/P.{so} PLAYER/C *)")
edge = hedge("(plays/P.so mary/C *)")
edge.match(pattern)  # [{"PLAYER": mary/C}]
```

--------------------------------

### Main functions

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/api.md

This section details the main functions available in the Hyperbase API.

```APIDOC
## Main functions

::: hyperbase
```

--------------------------------

### Get Total Atom Count of Hyperedge

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

The `size()` method calculates the total number of atoms across all depths within a hyperedge. This provides a measure of the hyperedge's complexity.

```python
>>> edge.size()
5
```

--------------------------------

### Exploring Hyperedge Structure

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

Methods for inspecting the components and properties of a hyperedge.

```APIDOC
## GET /hyperedge/atoms

### Description
Retrieves the set of unique atoms within a hyperedge.

### Method
GET

### Endpoint
/hyperedge/atoms

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to analyze.

### Response
#### Success Response (200)
- **atoms** (set) - A set of unique atoms in the hyperedge.

### Response Example
{
  "atoms": "{the/Md, of/Br, mayor/Cc, city/Cs}"
}

## GET /hyperedge/all_atoms

### Description
Retrieves a list of all atoms in a hyperedge, including duplicates.

### Method
GET

### Endpoint
/hyperedge/all_atoms

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to analyze.

### Response
#### Success Response (200)
- **all_atoms** (list) - A list of all atoms, including duplicates.

### Response Example
{
  "all_atoms": "[the/Md, of/Br, mayor/Cc, the/Md, city/Cs]"
}

## GET /hyperedge/size

### Description
Calculates the total number of atoms in a hyperedge at all depths.

### Method
GET

### Endpoint
/hyperedge/size

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to analyze.

### Response
#### Success Response (200)
- **size** (integer) - The total number of atoms.

### Response Example
{
  "size": 5
}

## GET /hyperedge/depth

### Description
Determines the maximal nesting depth of a hyperedge.

### Method
GET

### Endpoint
/hyperedge/depth

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to analyze.

### Response
#### Success Response (200)
- **depth** (integer) - The maximal nesting depth.

### Response Example
{
  "depth": 3
}

## GET /hyperedge/subedges

### Description
Retrieves the set of all subedges contained within a hyperedge, including atoms and the edge itself.

### Method
GET

### Endpoint
/hyperedge/subedges

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to analyze.

### Response
#### Success Response (200)
- **subedges** (set) - A set of all subedges.

### Response Example
{
  "subedges": "{(is/P.so (the/Md sky/Cc) blue/Cc), is/P.so, (the/Md sky/Cc), the/Md, sky/Cc, blue/Cc}"
}

## GET /hyperedge/contains

### Description
Checks if a given hyperedge is contained within another hyperedge.

### Method
GET

### Endpoint
/hyperedge/contains

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge to check within.
- **sub_edge** (string) - Required - The hyperedge to search for.

### Response
#### Success Response (200)
- **contains** (boolean) - True if the sub_edge is contained, False otherwise.

### Response Example
{
  "contains": true
}

## GET /hyperedge/atom_with_type

### Description
Finds the first atom in a hyperedge that matches a specific type.

### Method
GET

### Endpoint
/hyperedge/atom_with_type

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to analyze.
- **type** (string) - Required - The type of atom to find.

### Response
#### Success Response (200)
- **atom** (string) - The first atom found with the specified type, or null if not found.

### Response Example
{
  "atom": "sky/Cc"
}

## GET /hyperedge/connector_atom

### Description
Retrieves the innermost atom of the connector, traversing through modifier structures.

### Method
GET

### Endpoint
/hyperedge/connector_atom

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to analyze.

### Response
#### Success Response (200)
- **connector_atom** (string) - The connector atom, or null if none exists.

### Response Example
{
  "connector_atom": "like/P.so"
}

## GET /hyperedge/inner_atom

### Description
Retrieves the inner atom of a modifier structure.

### Method
GET

### Endpoint
/hyperedge/inner_atom

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to analyze.

### Response
#### Success Response (200)
- **inner_atom** (string) - The inner atom, or the atom itself if it's an atom.

### Response Example
{
  "inner_atom": "shoes/C"
}
```

--------------------------------

### Pattern Matching with `match()`

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Use the `match()` method to find patterns within hyperedges. Supports wildcards like `*` and `(*)` for flexible matching and variable extraction. Returns a list of dictionaries representing successful matches.

```python
from hyperbase import hedge

edge = hedge("(plays/P.so mary/C chess/C)")

# Simple wildcard matching (* matches anything)
pattern = hedge("(plays/P.so * *)")
matches = edge.match(pattern)
print(matches)  # [{}] - match found, no variables
```

--------------------------------

### Infer Type of Non-Atomic Hyperedge

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Observe that the type of a non-atomic hyperedge is inferred from its connector's type. For example, a predicate (P) connector results in a relation (R) edge type.

```python
edge = hedge("(likes/P.so mary/Cp chess/Cc)")
>>> edge.t
'R'
>>> edge.mt
'R'
>>> edge.ct
'P'
```

--------------------------------

### Functional Patterns for Edge Matching

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Demonstrates using functional patterns like `atoms` and `var` with `hedge.match()` for sophisticated edge matching. `atoms` checks for specific atoms at any depth, while `var` captures subexpressions.

```python
from hyperbase import hedge

# atoms: match edges containing specific atoms at any depth
edge = hedge("(is/M (not/M going/P))")

pattern1 = hedge("(atoms going/P)")
print(edge.match(pattern1))  # [{}] - going/P found at depth

pattern2 = hedge("(atoms not/M going/P)")
print(edge.match(pattern2))  # [{}] - both atoms present

pattern3 = hedge("(atoms like/P)")
print(edge.match(pattern3))  # [] - like/P not in edge

# atoms with wildcards
pattern4 = hedge("(atoms not/M */P)")
print(edge.match(pattern4))  # [{}] - not/M and any predicate

# var: capture complex expressions in a variable
edge2 = hedge("(claims/P.so mary/C (is/P.sc berlin/C nice/C))")

pattern = hedge("(var (is/P.{sc} * *) STATEMENT)")
matches = edge2.match("(claims/P.so * STATEMENT)")
print(matches)  # [{'STATEMENT': (is/P.sc berlin/C nice/C)}]

# Combine var with other patterns
pattern = hedge("(var (*/P.{so} ACTOR/C *) CLAIM)")
matches = edge2.match(pattern)
print(matches)  # Captures both the CLAIM and ACTOR within it
```

--------------------------------

### Build Hyperedge from Python List

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Construct hyperedges programmatically using Python lists, which is convenient for dynamic edge creation.

```python
edge = hedge(["likes/P.so", "mary/Cp", "chess/Cc"])
>>> edge
(likes/P.so mary/Cp chess/Cc)
```

--------------------------------

### Implement a Custom RSS Reader

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/readers.md

Subclass `Reader` to create a custom RSS reader. Implement `accepts` to identify RSS sources and `read` to yield text blocks from feed entries. Register the reader using `register_reader`.

```python
from hyperbase.readers import Reader, register_reader

class RSSReader(Reader):
    more_general = ("url",)  # take priority over the generic URL reader

    @staticmethod
    def accepts(source: str) -> bool:
        return source.endswith(".rss") or source.endswith("/feed")

    def read(self, source: str):
        import feedparser
        feed = feedparser.parse(source)
        for entry in feed.entries:
            # yield the text content of each entry as a block
            yield entry.get("summary", "")

    def source_info(self, source: str):
        return {"source_type": "rss", "source": source}

register_reader("rss", RSSReader)
```

--------------------------------

### Parse Natural Language to Hypergraphs

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Instantiates parser plugins using `get_parser()` to convert natural language text into semantic hypergraphs. Parsers return `ParseResult` objects.

```python
from hyperbase import get_parser

# Get an AlphaBeta parser for English
parser = get_parser("alphabeta", lang="en")

# Parse a sentence
text = "The sky is blue."
for result in parser.parse(text):
    print(result.edge)      # The parsed hyperedge
    print(result.text)      # Original sentence text
    print(result.tokens)    # Tokenized sentence
```

```python
from hyperbase import get_parser

parser = get_parser("alphabeta", lang="en")

# Parse multiple sentences
text = "Berlin is nice. Mary likes chess."
results = list(parser.parse(text))
for result in results:
    print(f"{result.text} -> {result.edge}")
```

```python
from hyperbase import get_parser

parser = get_parser("alphabeta", lang="en")

# Parse with progress bar for longer texts
results = parser.parse(
    "The Turing test was developed by Alan Turing. It tests machine intelligence.",
    batch_size=8,
    progress=True
)
for result in results:
    print(result.edge)
```

```python
from hyperbase import get_parser

parser = get_parser("alphabeta", lang="en")

# Parse single sentence directly
results = parser.parse_sentence("Einstein discovered relativity.")
print(results[0].edge)
```

```python
from hyperbase import get_parser

parser = get_parser("alphabeta", lang="en")

# Write results to JSONL file
parser.parse_to_jsonl("The sky is blue. Birds are singing.", "output.jsonl")
```

```python
from hyperbase.parsers import list_parsers

# List available parsers
for name, entry_point in list_parsers().items():
    print(f"{name}: {entry_point.value}")
```

--------------------------------

### Count Patterns in Hypergraph

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/discovering-patterns.md

Initialize a PatternCounter and feed it primary hyperedges from a hypergraph database to count patterns. By default, it recurses into sub-structures.

```python
from hyperbase import hgraph
from hyperbase.patterns import PatternCounter

hg = hgraph("ai.db")
pc = PatternCounter()
for edge in hg.all():
    if hg.is_primary(edge):
        pc.count(edge)
```

--------------------------------

### Create Hyperedges with hedge()

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

Use the `hedge()` function to create hyperedges from strings in SH notation, Python sequences, existing Hyperedge or Atom objects, or ParseResult objects. It returns a `Hyperedge` instance or `None` if parsing fails.

```python
from hyperbase import hedge

# From a string
edge = hedge("(plays/P.so mary/C chess/C)")

# From a list
edge = hedge(["plays/P.so", "mary/C", "chess/C"])

# Atoms are returned for atomic inputs
atom = hedge("mary/C")
```

--------------------------------

### Pattern Matching

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

Methods for matching hyperedges against patterns using wildcards.

```APIDOC
## POST /hyperedge/match

### Description
Matches a hyperedge against a pattern. Patterns can include wildcards like `*`, `.`, `(*)`, and `...` for open-ended matching. Named wildcards can capture matched entities.

### Method
POST

### Endpoint
/hyperedge/match

### Parameters
#### Request Body
- **edge** (string) - Required - The hyperedge string to match against.
- **pattern** (string) - Required - The pattern string to use for matching.

### Request Example
{
  "edge": "(is/P.so (my/Mp name/Cn) mary/Cp)",
  "pattern": "(is/P.so (my/Mp name/Cn) *NAME)"
}

### Response
#### Success Response (200)
- **matches** (list) - A list of dictionaries, where each dictionary represents a successful match and contains captured variables. An empty list indicates no match.

### Response Example
{
  "matches": [{"NAME": "mary/Cp"}]
}
```

--------------------------------

### String Representations and Labels

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

Methods for obtaining string representations and human-readable labels of hyperedges.

```APIDOC
## GET /hyperedge/label

### Description
Generates a human-readable label for a hyperedge, approximating natural language word order and URL-decoding atom roots.

### Method
GET

### Endpoint
/hyperedge/label

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to generate a label for.

### Response
#### Success Response (200)
- **label** (string) - The human-readable label.

### Response Example
{
  "label": "berlin is nice"
}

## GET /hyperedge/str

### Description
Returns the SH notation string representation of a hyperedge.

### Method
GET

### Endpoint
/hyperedge/str

### Parameters
#### Query Parameters
- **edge** (string) - Required - The hyperedge string to represent.

### Response
#### Success Response (200)
- **str_representation** (string) - The SH notation string.

### Response Example
{
  "str_representation": "(is/P.so berlin/Cp.s nice/Cc)"
}
```

--------------------------------

### Generate Human-Readable Hyperedge Labels

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Create a natural language approximation of a hyperedge's meaning using the `label()` method. This is particularly useful for simple relations.

```python
hedge("(is/P.so paris/Cp nice/Cc)").label()
'paris is nice'

hedge("(red/M shoes/Cc)").label()
'red shoes'
```

--------------------------------

### Combining Concepts: 'capital of Germany'

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/overview.md

Shows how hyperedges can combine concepts to define a new one. 'of' acts as the connector, linking 'capital' and 'germany'.

```plaintext
(of capital germany)
```

--------------------------------

### Match hyperedges using patterns in Python

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/patterns.md

Utilize the `hedge.match()` method in Python to check if a hyperedge conforms to a defined pattern. An empty list is returned if there is no match.

```python
from hyperbase import hedge
pattern = hedge("(plays/P.so * *)")
edge = hedge("(plays/P.so alice/C chess/C)")
edge.match(pattern)  # returns [{}]
```

```python
from hyperbase import hedge
edge = hedge("(likes/P.so alice/C chess/C)")
edge.match(pattern)  # returns []
```

--------------------------------

### Specifying Conditions: 'when the sky is blue'

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/overview.md

Shows how hyperedges can specify conditions within a proposition. 'when' is the connector for the condition '(is (the sky) blue)'.

```plaintext
(when (is (the sky) blue))
```

--------------------------------

### Discover Common Patterns with PatternCounter

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Use PatternCounter to find recurring structures in hyperedges. Configure options like count_subedges, expansions, and match_roots for focused analysis. Requires importing hedge and PatternCounter.

```python
from hyperbase import hedge
from hyperbase.patterns import PatternCounter

# Sample hyperedges (typically loaded from parsed text)
edges = [
    hedge("(is/P.sc berlin/C nice/C)"),
    hedge("(is/P.sc paris/C beautiful/C)"),
    hedge("(plays/P.so mary/C chess/C)"),
    hedge("(plays/P.so john/C tennis/C)"),
    hedge("(likes/P.so alice/C music/C)"),
    hedge("(the/M sky/C)"),
    hedge("(the/M city/C)"),
]

# Basic pattern counting
pc = PatternCounter()
for edge in edges:
    pc.count(edge)

# Get most common patterns
print(pc.patterns.most_common(5))
# [((*/M */C), 2), ((*/P.so */C */C), 3), ((*/P.sc */C */C), 2), ...]

# Focus on top-level only (no subedge expansion)
pc = PatternCounter(count_subedges=False)
for edge in edges:
    pc.count(edge)
print(pc.patterns.most_common(5))

# Focus on specific structures using expansions
pc = PatternCounter(expansions={" (*/P * * ...)"})
for edge in edges:
    pc.count(edge)
print(pc.patterns.most_common(5))

# Include explicit roots for predicates
pc = PatternCounter(
    expansions={" (*/P * * ...)"},
    match_roots={"*/P"}
)
for edge in edges:
    pc.count(edge)
print(pc.patterns.most_common(5))
# Shows actual predicate roots like is/P, plays/P, likes/P
```

--------------------------------

### Define Text for Parsing

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/parsing-a-sentence.md

Assigns a sample sentence to a variable for parsing.

```python
text = "The Turing test, developed by Alan Turing in 1950, is a test of machine intelligence."
```

--------------------------------

### Parse Text File to JSONL

Source: https://context7.com/hyperquest-hq/hyperbase/llms.txt

Convert a text file into JSONL format using a specified parser and language.

```bash
hyperbase read article.txt -o output.jsonl --parser alphabeta --lang en
```

--------------------------------

### Parse Source to JSONL

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/parsers.md

Parse text from a source file and write all results directly to a JSONL file, with an optional progress bar.

```python
# Or write everything to a JSONL file
parser.parse_source_to_jsonl("article.txt", "output.jsonl", progress=True)
```

--------------------------------

### CLI: Extract Raw Text Blocks

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/readers.md

Use the `hyperbase read` command with an output file specified to extract raw text blocks from a source without parsing.

```bash
# Extract raw text blocks (no parsing)
hyperbase read article.txt -o output.txt
```

--------------------------------

### Parse File to JSONL

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/parsers.md

Parses a text file and outputs the results in JSONL format using a specified parser and language.

```bash
# Parse a file to JSONL
hyperbase read article.txt -o output.jsonl --parser alphabeta --lang en
```

--------------------------------

### Retrieve Arguments by Role

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Shows how to retrieve specific arguments from a hyperedge based on their designated role. This is useful for accessing subject, object, or other argument types.

```python
>>> edge.arguments_with_role("s")
[paris/Cp]
>>> edge.arguments_with_role("o")
[nice/Cc]
```

--------------------------------

### Parse Text and Print Hyperedges

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/parsing-a-sentence.md

Parses the provided text and prints the SH notation string for the hyperedge corresponding to each sentence. Requires the parser and text variables to be defined.

```python
results = parser.parse(text)
for result in results:
    print(result.edge)
```

--------------------------------

### Parse Source to JSONL with Auto-Detected Reader

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/readers.md

Use the `Parser`'s `parse_source_to_jsonl` method to parse text and write directly to a JSONL file. The reader is auto-detected. Progress can be displayed.

```python
# Or write everything to a JSONL file in one call
parser.parse_source_to_jsonl("article.txt", "output.jsonl", progress=True)
```

--------------------------------

### UniqueAtom Handling

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/manual/hyperedges.md

Utilities for managing identity-based comparison of atoms.

```APIDOC
## UniqueAtom

By default, atoms are compared by value. When identity-based comparison is needed (e.g., to distinguish different occurrences of the same atom), Hyperbase provides `UniqueAtom` and the utility functions `unique()` and `non_unique()`.
```

--------------------------------

### Replace Atom with Hyperedge

Source: https://github.com/hyperquest-hq/hyperbase/blob/master/docs/tutorials/playing-with-hyperedges.md

Shows how to replace an existing atom within a hyperedge with a new, non-atomic hyperedge. This highlights the flexibility in modifying hyperedge structures.

```python
>>> edge.replace_atom(hedge("paris/Cp"), hedge("(the/Md city/Cc)"))
(is/P.so (the/Md city/Cc) nice/Cc)
```