Knows is a powerful and user-friendly tool for generating property graphs. These graphs are crucial in many fields. Knows supports multiple output formats, schema files and basic visualization capabilities, making it a go-to tool for researchers, educators and data enthusiasts.

Quick Start ⚡

Install with uv, pipx or pip:

uv tool install "knows[all]"
# or: pipx install "knows[all]"
# or: pip install "knows[all]"

# Generate a random graph (default: YARS-PG format)
knows

# 10 nodes, 5 edges → GraphML file
knows -n 10 -e 5 -f graphml graph.graphml

# Visualize as PNG
knows -n 20 -e 15 -f png graph.png

# Export to CSV (creates graph_nodes.csv + graph_edges.csv)
knows -n 10 -e 8 -f csv graph.csv

# Use a custom schema
knows -n 10 -e 15 --schema schema-examples/employee_schema.json -f cypher

Or with Docker - no installation needed:

docker run --rm lszeremeta/knows -n 10 -e 5 -f graphml

Run knows -h to see all options. For more install methods see the Installation section, for all options and more examples see the Usage section below. Custom node/edge types are covered in SCHEMA.md, writing your own output formats in PLUGINS.md.

Key Features 🚀

• Customizable Graph Generation: Tailor your graphs by specifying the number of nodes and edges.
• Diverse Output Formats: Export graphs in formats like GraphML, YARS-PG 5.0, CSV, Cypher, GEXF, GML, JSON, and others.
• Flexible Output Options: Display results in the console, redirect them, or save them directly to a file.
• Integrated Graph Visualization: Conveniently visualize your graphs in SVG, PNG, JPG, or PDF format.
• Intuitive Command-Line Interface (CLI): A user-friendly CLI for streamlined graph generation and visualization.
• Docker Compatibility: Deploy Knows in Docker containers for a consistent and isolated runtime environment.
• Selectable Properties: Choose which node and edge properties should be generated.
• Custom Schema Support: Define custom node/edge types and properties using GQL-inspired (ISO/IEC 39075) JSON schema files. Includes JSON Schema for validation. Schemas support many data types (String, Int, Float, Date, Duration, enums, and more), symmetric edge properties (for mutual relationships), computed node properties (like degree), and type constraints. See SCHEMA.md for full documentation.
• Reproducible graphs: Ensure deterministic outputs by setting the -s/--seed option regardless of the selected output format.
• Extensible Plugin System: All output formats are plugins discovered at runtime. Add new formats by installing a pip package - no changes to the core codebase required. See PLUGINS.md for details.

Note on reproducibility: The -s/--seed option makes the random aspects of graph generation deterministic within the same software environment. Results may still differ across versions of Python or dependencies.

Graph Structure 🕸️

Built-in graph structure:

• Generates graphs with specified or random nodes and edges.
• Creates directed graphs.
• Nodes are labeled Person with unique IDs (N1, N2, N3, ..., Nn).
• Nodes feature firstName and lastName properties by default.
• Edges are labeled knows and include strength [1..100] and lastMeetingDate [1955-01-01..2025-06-28] properties by default.
• Additional node properties:
  • favoriteColor
  • company
  • job
  • phoneNumber
  • postalAddress
  • friendCount (actual node degree - number of unique connections)
  • preferredContactMethod [inPerson, email, postalMail, phone, textMessage, videoCall, noPreference]
• Additional edge properties:
  • lastMeetingCity
  • meetingCount [1..10000]
• Edges connect random pairs of distinct nodes, avoiding self-loops and duplicate edges (mutual edges A→B and B→A are allowed).
• If edges connect the same nodes in both directions, the paired edges share lastMeetingCity, lastMeetingDate, and meetingCount values.

You can define custom graph structures using schema files. See SCHEMA.md for details and examples.

Plugin System 🔌

Knows uses a modular plugin architecture for output formats. Every format - including all 14 built-in ones - is a plugin discovered at runtime via Python's standard entry_points mechanism. This means you can:

• Install new formats from pip packages without touching the Knows source code.
• Create your own formats for domain-specific needs (custom serializations, database loaders, etc.).
• Add formats to the core by implementing a simple class and registering it.

A format plugin is any Python object that provides a name, description, output_kind, default_extension, and a convert(graph, ctx) method. No base class inheritance is required - Knows uses structural typing (duck typing with protocol checks). The ctx parameter is a ConvertContext carrying visualization settings (viz_limit, show_info) that visual formats use and text formats can ignore. Plugins can also produce visual output - either by using the built-in GraphDrawer helper or a custom rendering pipeline.

For a step-by-step guide on creating and registering plugins (including visual formats), see PLUGINS.md.

Installation 🛠️

You can install knows via PyPI, Docker or run it from the source code.

Install via PyPI 📦

1. Installation with uv, pipx or pip:

   uv tool install "knows[all]"

   pipx install "knows[all]"

   pip install "knows[all]"

   Knows is a command-line tool, so uv tool install and pipx install are the recommended options - they install Knows into an isolated environment and make the knows command available globally.

   The all extra installs all optional dependencies - currently the matplotlib and scipy libraries needed for graph visualization (svg, png, jpg and pdf formats and the -d option). You can omit [all] if you don't need visualization. knows[all] is an alias for knows[draw] - both work.

2. Running Knows:

   knows [options]

Docker Deployment 🐳

From Docker Hub

1. Pull Image:

   docker pull lszeremeta/knows

2. Run Container:

   docker run --rm lszeremeta/knows [options]

Building from Source

1. Build Image:

   docker build -t knows .

2. Run Container:

   docker run --rm knows [options]

See Docker examples in Practical Examples section.

Python from Source 🐍

1. Clone Repository:

   git clone git@github.com:lszeremeta/knows.git
   cd knows

2. Install Requirements:

   pip install ".[all]"

3. Execute Knows:

   python -m knows [options]

Install Tkinter for Graph Visualization 🖼️

The -d/--draw option requires Tkinter. You can check whether visualization is available in your environment with knows --version.

• Ubuntu:

  sudo apt update
  sudo apt install python3-tk

  See Installing Tkinter on Ubuntu for details.

• macOS (Homebrew):

  brew install python3
  brew install python-tk

  See Installing Tkinter on macOS for details.

• Windows: On Windows, Tkinter should be installed by default with Python. No additional steps required.

Usage 💡

Basic Usage

usage: knows [-h] [-n NODES] [-e EDGES] [-s SEED] [-v]
             [-f {graphml,yarspg,csv,cypher,gexf,gml,svg,png,jpg,pdf,adjacency_list,multiline_adjacency_list,edge_list,json}]
             [--schema FILE] [-l LOCALE]
             [-np [{firstName,lastName,company,job,phoneNumber,favoriteColor,postalAddress,preferredContactMethod,friendCount} ...]]
             [-ep [{strength,lastMeetingCity,lastMeetingDate,meetingCount} ...]] [-ap] [-d] [--debug] [--limit N] [--no-limit]
             [--hide-info] [output]

Available options may vary depending on the version. To display all available options with their descriptions use knows -h.

Positional arguments

• output: Optional path to save the graph. For CSV format two files will be created: *_nodes.csv and *_edges.csv.

Options

• -h, --help: Show help message and exit.
• -n NODES, --nodes NODES: Number of nodes in the graph. Selected randomly if not specified.
• -e EDGES, --edges EDGES: Number of edges in the graph. Selected randomly if not specified.
• -s SEED, --seed SEED: Seed for random number generation to ensure reproducible results (also between various output formats).
• -v, --version: Show program version, environment and plugin diagnostics, and exit. The report includes dependency versions, visualization availability, install source (PyPI, Docker, local) and installed format plugins - paste it into bug reports.
• -f {graphml,yarspg,csv,cypher,gexf,gml,svg,png,jpg,pdf,adjacency_list,multiline_adjacency_list,edge_list,json}, --format {graphml,yarspg,csv,cypher,gexf,gml,svg,png,jpg,pdf,adjacency_list,multiline_adjacency_list,edge_list,json}: Format to output the graph. Default: yarspg. The svg, png, jpg and pdf formats are for simple graph visualization.
• --schema FILE: Path to JSON schema file defining custom node/edge types and properties. When specified, overrides -np, -ep, and -ap options. GQL-inspired schema format (ISO/IEC 39075). See SCHEMA.md for details.
• -l LOCALE, --locale LOCALE: Locale code for generated property values (e.g. pl_PL, de_DE, ja_JP). Default: en_US. See the list of supported locales.
• -np [{firstName,lastName,company,job,phoneNumber,favoriteColor,postalAddress,preferredContactMethod,friendCount} ...], --node-props [{firstName,lastName,company,job,phoneNumber,favoriteColor,postalAddress,preferredContactMethod,friendCount} ...]: Space-separated node properties. Available: firstName, lastName, company, job, phoneNumber, favoriteColor, postalAddress, preferredContactMethod, friendCount. Ignored when --schema is used.
• -ep [{strength,lastMeetingCity,lastMeetingDate,meetingCount} ...],
  --edge-props [{strength,lastMeetingCity,lastMeetingDate,meetingCount} ...]:
  Space-separated edge properties. Available: strength, lastMeetingCity, lastMeetingDate, meetingCount. Ignored when --schema is used.
• -ap, --all-props: Use all available node and edge properties. Ignored when --schema is used.
• -d, --draw: Show interactive graph window. Requires Tkinter. May not work in Docker.
• --debug: Show full tracebacks instead of short error messages.

Graphics output options (svg, png, jpg, pdf, -d)

• --limit N: Maximum nodes to display (default: 50). Shows subgraph centered on most connected nodes.
• --no-limit: Show full graph without node limit.
• --hide-info: Hide node count info (e.g., 50/200 nodes) from output.

Practical Examples 🌟

1. Create a random graph in YARS-PG 5.0 format and show it:

   knows
   # or
   docker run --rm lszeremeta/knows

2. Create a 100-node, 70-edge graph in GraphML format:

   knows -n 100 -e 70 -f graphml > graph.graphml
   # or
   knows -n 100 -e 70 -f graphml graph.graphml
   # or
   docker run --rm lszeremeta/knows -n 100 -e 70 -f graphml > graph.graphml
   # or
   docker run --rm -v "$(pwd)":/data lszeremeta/knows -n 100 -e 70 -f graphml /data/graph.graphml

3. Create a random graph in CSV format and save to files (nodes are written to standard output, edges to standard error):

   knows -f csv > nodes.csv 2> edges.csv
   # or
   knows -f csv graph.csv
   # or
   docker run --rm lszeremeta/knows -f csv > nodes.csv 2> edges.csv
   # or
   docker run --rm -v "$(pwd)":/data lszeremeta/knows -f csv /data/graph.csv

   The latter command creates graph_nodes.csv and graph_edges.csv.
4. Create a 50-node, 20-edge graph in Cypher format:

   knows -n 50 -e 20 -f cypher > graph.cypher
   # or
   knows -n 50 -e 20 -f cypher graph.cypher
   # or
   docker run --rm lszeremeta/knows -n 50 -e 20 -f cypher > graph.cypher
   # or
   docker run --rm -v "$(pwd)":/data lszeremeta/knows -n 50 -e 20 -f cypher /data/graph.cypher

5. Create a 100-node, 50-edge graph in YARS-PG format:

   knows -n 100 -e 50 > graph.yarspg
   # or
   knows -n 100 -e 50 graph.yarspg
   # or
   docker run --rm lszeremeta/knows -n 100 -e 50 > graph.yarspg
   # or
   docker run --rm -v "$(pwd)":/data lszeremeta/knows -n 100 -e 50 /data/graph.yarspg

6. Create, save, and visualize a 100-node, 50-edge graph in SVG:

   knows -n 100 -e 50 -f svg -d > graph.svg
   # or
   knows -n 100 -e 50 -f svg -d graph.svg

7. Create, save a 70-node, 50-edge graph in SVG:

   knows -n 70 -e 50 -f svg > graph.svg
   # or
   knows -n 70 -e 50 -f svg graph.svg
   # or
   docker run --rm lszeremeta/knows -n 70 -e 50 -f svg > graph.svg
   # or
   docker run --rm -v "$(pwd)":/data lszeremeta/knows -n 70 -e 50 -f svg /data/graph.svg

8. Create, save a 10-node, 5-edge graph in PNG:

   knows -n 10 -e 5 -f png > graph.png
   # or
   knows -n 10 -e 5 -f png graph.png
   # or
   docker run --rm lszeremeta/knows -n 10 -e 5 -f png > graph.png
   # or
   docker run --rm -v "$(pwd)":/data lszeremeta/knows -n 10 -e 5 -f png /data/graph.png

9. Create a graph in JSON format:

   knows -f json > graph.json
   # or
   knows -f json graph.json
   # or
   docker run --rm lszeremeta/knows -f json > graph.json
   # or
   docker run --rm -v "$(pwd)":/data lszeremeta/knows -f json /data/graph.json

10. Create a graph with custom properties (20 nodes, 10 edges) and show it:

knows -n 20 -e 10 -np firstName favoriteColor job -ep lastMeetingCity
# or
docker run --rm lszeremeta/knows -n 20 -e 10 -np firstName favoriteColor job -ep lastMeetingCity

11. Create a graph with all possible properties in YARS-PG format and save it to file:

knows -ap > graph.yarspg
# or
knows -ap graph.yarspg
# or
docker run --rm lszeremeta/knows -ap > graph.yarspg
# or
docker run --rm -v "$(pwd)":/data lszeremeta/knows -ap /data/graph.yarspg

12. Generate a reproducible graph in CSV by setting a seed:

knows -n 3 -e 2 -s 43 -f csv
# or
docker run --rm lszeremeta/knows -n 3 -e 2 -s 43 -f csv

Running the command again with the same seed will produce the identical graph, provided the environment and dependencies remain unchanged.

13. Generate the same graph as above but in YARS-PG format:

knows -n 3 -e 2 -s 43
# or
docker run --rm lszeremeta/knows -n 3 -e 2 -s 43

14. Generate a graph using a custom schema file:

knows -n 10 -e 15 --schema schema-examples/employee_schema.json
# or
knows -n 10 -e 15 --schema schema-examples/employee_schema.json -f cypher > employees.cypher
# or with Docker (using built-in example schemas)
docker run --rm lszeremeta/knows --schema /app/schema-examples/employee_schema.json -n 10 -e 15
docker run --rm -v "$(pwd)":/data lszeremeta/knows --schema /app/schema-examples/employee_schema.json -n 10 -e 15 -f cypher /data/employees.cypher

See SCHEMA.md for full schema documentation and more examples.

15. Visualize a large graph with custom node limit:

knows -n 500 -e 300 -f svg --limit 100 > graph.svg
# or
docker run --rm lszeremeta/knows -n 500 -e 300 -f svg --limit 100 > graph.svg
# or
docker run --rm -v "$(pwd)":/data lszeremeta/knows -n 500 -e 300 -f svg --limit 100 /data/graph.svg

This limits the visualization to 100 nodes (default is 50), centered on the most connected nodes.

16. Visualize the full graph without node limit:

knows -n 200 -e 150 -f png --no-limit > graph.png
# or
docker run --rm lszeremeta/knows -n 200 -e 150 -f png --no-limit > graph.png
# or
docker run --rm -v "$(pwd)":/data lszeremeta/knows -n 200 -e 150 -f png --no-limit /data/graph.png

17. Create visualization without node count info:

knows -n 300 -e 200 -f svg --hide-info > graph.svg
# or
docker run --rm lszeremeta/knows -n 300 -e 200 -f svg --hide-info > graph.svg
# or
docker run --rm -v "$(pwd)":/data lszeremeta/knows -n 300 -e 200 -f svg --hide-info /data/graph.svg

18. Create a graph with nodes only (no edges):

knows -n 10 -e 0 -f graphml > nodes_only.graphml
# or
docker run --rm lszeremeta/knows -n 10 -e 0 -f graphml > nodes_only.graphml
# or
docker run --rm -v "$(pwd)":/data lszeremeta/knows -n 10 -e 0 -f graphml /data/nodes_only.graphml

19. Generate a graph with values in another language:

knows -n 10 -e 5 -l pl_PL -f cypher
# or
docker run --rm lszeremeta/knows -n 10 -e 5 -l pl_PL -f cypher

Note: On Windows PowerShell, replace $(pwd) with ${PWD}. On Windows Command Prompt, use %cd%.

Contribute to Knows 👥

Your ideas and contributions can make Knows even better! If you're new to open source, read How to Contribute to Open Source and CONTRIBUTING.md.

License 📜

Knows is licensed under the MIT License.