agent-docs 1.0.0

package/docs/GRAPHML.md

@@ -0,0 +1,337 @@
+# GraphML Format Specification
+
+> **Version**: 1.0.0
+
+XML-based format for graph serialization defined by GraphML specification (DTD
+and XSD).
+
+**Related Docs:** [GRAPHENGINE.md](GRAPHENGINE.md),
+[TINKERPOP.md](TINKERPOP.md), [GRAPHSON.md](GRAPHSON.md), [GRYO.md](GRYO.md),
+[GRAPHBINARY.md](GRAPHBINARY.md), [CODEANALYZER.md](CODEANALYZER.md)
+
+## Overview
+
+GraphML: XML-based format for representing graph structures. TinkerGraph can
+load/save graphs in GraphML format. Enables graph persistence and exchange.
+Useful for testing and development. Conforms to GraphML DTD and XSD
+specifications. Human-readable XML format.
+
+## GraphML Document Structure
+
+### Root Element: `<graphml>`
+
+Root element containing namespace declarations, `<key>` elements (property
+definitions), and `<graph>` elements (graph data). Keys must appear before
+graphs. Multiple graphs allowed.
+
+**Attributes:** `xmlns` (XML namespace, typically
+`http://graphml.graphdrawing.org/xmlns`), `xmlns:xsi` (XML Schema instance
+namespace), `xsi:schemaLocation` (Location of XSD schema)
+
+**Example:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<graphml
+    xmlns="http://graphml.graphdrawing.org/xmlns"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns
+         http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd"
+>
+    <!-- keys and graphs -->
+</graphml>
+```
+
+### Key Element: `<key>`
+
+Defines property keys used in graph elements. Must appear before `<graph>`
+elements. Optional `<desc>` and `<default>`.
+
+**Attributes:** `id` (required, unique identifier), `for` (optional, element
+type: `all`, `graph`, `node`, `edge`, default: `all`), `attr.name` (optional,
+property name), `attr.type` (optional, data type: `string`, `int`, `long`,
+`float`, `double`, `boolean`, default: `string`), `attr.list` (optional, whether
+property is a list: `true`/`false`, default: `false`), `attr.domain` (optional,
+domain specification)
+
+**Example:**
+
+```xml
+<key id="name" for="node" attr.name="name" attr.type="string"/>
+<key id="weight" for="edge" attr.name="weight" attr.type="double"/>
+```
+
+### Graph Element: `<graph>`
+
+Represents a graph structure. Contains `<node>`, `<edge>`, `<hyperedge>`, and
+`<data>` elements.
+
+**Attributes:** `id` (optional, unique identifier), `edgedefault` (required,
+default edge direction: `directed` or `undirected`), `parse.nodes`,
+`parse.edges` (optional, hints for parsers to pre-allocate memory),
+`parse.maxindegree`, `parse.maxoutdegree` (optional, hints for optimizing data
+structures), `parse.nodeids`, `parse.edgeids` (optional, ID type: `canonical` =
+sequential integers starting at 0, `free` = arbitrary IDs), `parse.order`
+(optional, element ordering: `nodesfirst`, `edgesfirst`, `adjacencylist`)
+
+### Node Element: `<node>`
+
+Represents a vertex. Contains `<data>` elements for properties, optional
+`<port>` elements (for hyperedges), optional nested `<graph>` (for hierarchical
+graphs).
+
+**Attributes:** `id` (required, unique identifier)
+
+**Example:**
+
+```xml
+<node id="1">
+    <data key="name">Vertex 1</data>
+    <data key="type">Person</data>
+</node>
+```
+
+### Edge Element: `<edge>`
+
+Represents an edge connecting two nodes. Contains `<data>` elements for
+properties, optional nested `<graph>`.
+
+**Attributes:** `id` (optional, unique identifier), `source` (required, ID of
+source node), `target` (required, ID of target node), `directed` (optional,
+whether edge is directed: `true`/`false`, defaults to `edgedefault` from graph)
+
+**Example:**
+
+```xml
+<edge id="e1" source="1" target="2">
+    <data key="weight">1.5</data>
+</edge>
+```
+
+### Hyperedge Element: `<hyperedge>`
+
+Represents hyperedge connecting multiple nodes (n-ary relationship). Contains
+`<endpoint>` elements, `<data>` elements, optional nested `<graph>`.
+
+**Attributes:** `id` (optional, unique identifier)
+
+### Endpoint Element: `<endpoint>`
+
+Represents connection point in hyperedge. Specifies which node and port the
+hyperedge connects to.
+
+**Attributes:** `id` (optional, unique identifier), `node` (required, ID of
+connected node), `port` (optional, port name on the node)
+
+### Port Element: `<port>`
+
+Represents port on a node (connection point for hyperedges). Used in
+hierarchical graphs and hyperedge connections.
+
+**Attributes:** `name` (required, port name/identifier)
+
+### Data Element: `<data>`
+
+Contains property value for graph, node, or edge. References a `<key>` element
+via `key` attribute. Can contain text content or nested elements.
+
+**Attributes:** `key` (required, ID of corresponding `<key>` element)
+
+### Desc/Default Elements
+
+- `<desc>`: Optional description element (text content)
+- `<default>`: Optional default value element (text content, used in `<key>`
+  elements)
+
+## Complete GraphML Example
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<graphml
+    xmlns="http://graphml.graphdrawing.org/xmlns"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns
+         http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd"
+>
+    <key id="name" for="node" attr.name="name" attr.type="string" />
+    <key id="weight" for="edge" attr.name="weight" attr.type="double" />
+    <graph id="G" edgedefault="directed">
+        <node id="1">
+            <data key="name">Vertex 1</data>
+        </node>
+        <node id="2">
+            <data key="name">Vertex 2</data>
+        </node>
+        <edge id="e1" source="1" target="2">
+            <data key="weight">1.5</data>
+        </edge>
+    </graph>
+</graphml>
+```
+
+## TinkerPop GraphML Support
+
+**GraphMLReader:** Reads GraphML files into TinkerPop graphs, parses all GraphML
+elements, handles property key definitions, supports all GraphML data types.
+Builder: `GraphMLReader.build().create()`. Methods:
+`readGraph(InputStream|File|URL, Graph)`. **Limitation:** Does not fully support
+hyperedges and ports (simplified to regular edges).
+
+**GraphMLWriter:** Writes TinkerPop graphs to GraphML format, generates valid
+GraphML documents, includes property key definitions. Builder:
+`GraphMLWriter.build().normalize(boolean).xmlMapper(XMLMapper).create()`.
+Methods: `writeGraph(OutputStream|File|URL, Graph)`. Configuration: `normalize`
+(default: false), `xmlMapper` (custom XML mapper). **Limitation:** Does not
+support hyperedges and ports (converts to regular edges).
+
+**Usage:**
+
+```java
+Graph graph = TinkerGraph.open();
+GraphReader reader = GraphMLReader.build().create();
+reader.readGraph(new FileInputStream("graph.graphml"), graph);
+
+GraphWriter writer = GraphMLWriter.build().create();
+writer.writeGraph(new FileOutputStream("graph.graphml"), graph);
+```
+
+**Limitations:** Does not support meta-properties (vertex properties on vertex
+properties) as GraphML specification does not define this concept. Hyperedges
+and ports are simplified to regular edges in TinkerPop implementation.
+
+## DTD Specification
+
+Document Type Definition (DTD) defines structure and validation rules.
+
+**Element Definitions:**
+
+- `<!ELEMENT graphml (key*,graph*)>`: Root element (keys before graphs, multiple
+  graphs allowed)
+- `<!ELEMENT key (desc?,default?)>`: Property key definition
+- `<!ELEMENT graph (data*,node*,edge*,hyperedge*)>`: Graph structure
+- `<!ELEMENT node (data*,port*,graph?)>`: Vertex (can contain nested graph,
+  ports)
+- `<!ELEMENT edge (data*,graph?)>`: Edge connecting two nodes
+- `<!ELEMENT hyperedge (data*,endpoint*,graph?)>`: Hyperedge connecting multiple
+  nodes
+- `<!ELEMENT endpoint (data*,port?)>`: Connection point in hyperedge
+- `<!ELEMENT port (data*,graph?)>`: Port on a node
+- `<!ELEMENT data (#PCDATA|desc|default)*>`: Property value
+- `<!ELEMENT desc (#PCDATA)>`: Description element
+- `<!ELEMENT default (#PCDATA)>`: Default value element
+
+**Attribute Definitions:**
+
+- `key`: `id` (required, ID), `for` (optional, `all|graph|node|edge`, default:
+  `all`), `attr.name`, `attr.type` (optional,
+  `string|int|long|float|double|boolean`, default: `string`), `attr.list`
+  (optional, `true|false`, default: `false`), `attr.domain` (optional)
+- `graph`: `id` (optional, ID), `edgedefault` (required, `directed|undirected`),
+  parsing attributes (optional)
+- `node`: `id` (required, ID)
+- `edge`: `id` (optional, ID), `source` (required, IDREF), `target` (required,
+  IDREF), `directed` (optional, `true|false`, defaults to graph `edgedefault`)
+- `data`: `key` (required, IDREF)
+- `endpoint`: `id` (optional, ID), `node` (required, IDREF), `port` (optional,
+  NMTOKEN)
+- `port`: `name` (required, NMTOKEN)
+
+## XSD Specification
+
+XML Schema Definition (XSD) provides schema validation. More expressive than DTD
+(data types, constraints), defines element/attribute types, supports namespace
+validation.
+
+**Complex Types:**
+
+- `graphml.type`: Root element type (sequence of `key.type` and `graph.type`,
+  keys before graphs)
+- `key.type`: Key element type (optional `desc` and `default`, attributes: `id`
+  (required, ID), `for` (optional, `key.for.type`, default: `all`), `attr.name`,
+  `attr.type` (optional, `key.attr.type.type`, default: `string`), `attr.list`
+  (optional, boolean, default: `false`), `attr.domain`)
+- `graph.type`: Graph element type (sequence of `data.type`, `node.type`,
+  `edge.type`, `hyperedge.type`, attributes: `id` (optional, ID), `edgedefault`
+  (required, `graph.edgedefault.type`), parsing attributes)
+- `node.type`: Node element type (sequence of `data.type`, `port.type`, optional
+  `graph.type`, attributes: `id` (required, ID))
+- `edge.type`: Edge element type (sequence of `data.type`, optional
+  `graph.type`, attributes: `id` (optional, ID), `source` (required, IDREF),
+  `target` (required, IDREF), `directed` (optional, `edge.directed.type`))
+- `hyperedge.type`: Hyperedge element type (sequence of `data.type`,
+  `endpoint.type`, optional `graph.type`, attributes: `id` (optional, ID))
+- `endpoint.type`: Endpoint element type (sequence of `data.type`, optional
+  `port.type`, attributes: `id` (optional, ID), `node` (required, IDREF), `port`
+  (optional, NMTOKEN))
+- `port.type`: Port element type (sequence of `data.type`, optional
+  `graph.type`, attributes: `name` (required, NMTOKEN))
+- `data.type`: Data element type (mixed content: text, `desc`, `default`,
+  attributes: `key` (required, IDREF))
+- `desc.type`: Description element type (text content)
+- `default.type`: Default value element type (text content)
+
+**Simple Types:**
+
+- `key.for.type`: Enumeration (`all`, `graph`, `node`, `edge`, default: `all`)
+- `key.attr.type.type`: Enumeration (`string`, `int`, `long`, `float`, `double`,
+  `boolean`, default: `string`)
+- `graph.edgedefault.type`: Enumeration (`directed`, `undirected`, required)
+- `edge.directed.type`: Boolean (`true`/`false`, optional, overrides graph
+  `edgedefault`)
+
+**Attribute Groups:**
+
+- `graph.extra.attrib`, `node.extra.attrib`, `edge.extra.attrib`: Extension
+  attributes for extension namespaces
+
+## Validation Rules
+
+**Document-Level:** Key IDs must be unique, keys must be defined before use,
+multiple graphs allowed.
+
+**Graph-Level:** Graph `id` must be unique if specified, `edgedefault` required,
+node/edge/hyperedge IDs must be unique within graph, port names must be unique
+within each node.
+
+**Node Rules:** Node `id` required and unique within graph, must be valid XML
+ID.
+
+**Edge Rules:** `source` and `target` required, must reference existing node IDs
+(IDREF constraint), `directed` overrides graph `edgedefault` if specified.
+
+**Hyperedge Rules:** `id` must be unique if specified, must contain at least one
+`<endpoint>`, endpoint `node` required and must reference existing node ID,
+endpoint `port` must reference existing port name if node has ports.
+
+**Port Rules:** `name` required and unique within node, must be valid XML
+NMTOKEN.
+
+**Data Rules:** `key` required, must reference defined key ID (IDREF
+constraint), value type must match key's `attr.type` if specified.
+
+**Type Validation:** String values (any text), integer/long (valid integer
+format), float/double (valid floating-point format), boolean (`true` or `false`,
+case-sensitive), list values (multiple values separated by whitespace when
+`attr.list="true"`).
+
+## Namespace Support
+
+**Default namespace:** `http://graphml.graphdrawing.org/xmlns`
+
+**XML Schema namespace:** `http://www.w3.org/2001/XMLSchema`
+
+**XML Schema Instance namespace:** `http://www.w3.org/2001/XMLSchema-instance`
+
+**Extension Namespaces:** Supports extension namespaces for custom
+elements/attributes. Custom attributes in extension namespaces allowed on all
+elements. Custom elements in extension namespaces allowed (must not conflict
+with core elements). Maintains compatibility with core specification when
+extensions used.
+
+## Extension Points
+
+GraphML allows custom extensions via namespaces: additional elements in
+extension namespaces, custom attributes on standard elements, extension elements
+can appear in standard element content where appropriate. Maintains backward
+compatibility: core parsers ignore unknown extension elements/attributes.
+Extension elements should follow GraphML structure patterns for consistency.

package/docs/GRAPHSON.md

@@ -0,0 +1,302 @@
+# GraphSON Format Specification
+
+> **Version**: 1.0.0
+
+JSON-based format for graph serialization used by Apache TinkerPop.
+
+**Related Docs:** [GRAPHENGINE.md](GRAPHENGINE.md),
+[TINKERPOP.md](TINKERPOP.md), [GRAPHML.md](GRAPHML.md), [GRYO.md](GRYO.md),
+[GRAPHBINARY.md](GRAPHBINARY.md), [CODEANALYZER.md](CODEANALYZER.md)
+
+## Overview
+
+GraphSON: JSON-based format for graph serialization. Multiple versions (v1, v2,
+v3) with different schemas. Compact and efficient for network transfer. Primary
+format for Gremlin Server communication. Supports typed and untyped property
+values. Human-readable JSON format. Suitable for API communication and web
+applications.
+
+## GraphSON Versions
+
+**GraphSON v1:** Original format, untyped properties, simple structure, basic
+JSON representation of graph elements. Use cases: legacy systems, simple graph
+representations, when type information is not required.
+
+**GraphSON v2:** Typed properties, includes meta-properties (vertex properties
+on vertex properties), more structured format, better type preservation. Use
+cases: when type information is important, complex property structures,
+meta-property support required.
+
+**GraphSON v3:** Compact format, optimized for network transfer, typed
+properties, improved efficiency over v2. Use cases: Gremlin Server
+communication, network transfer scenarios, high-performance requirements, modern
+applications.
+
+## TinkerPop GraphSON Support
+
+**Builder Pattern:**
+
+```java
+GraphSONReader reader = GraphSONReader.build()
+    .version(GraphSONVersion.V3_0)
+    .mapper(new ObjectMapper())
+    .create();
+
+GraphSONWriter writer = GraphSONWriter.build()
+    .version(GraphSONVersion.V3_0)
+    .embedTypes(true)
+    .includeNullProperties(false)
+    .normalize(false)
+    .mapper(new ObjectMapper())
+    .create();
+```
+
+**Reader Methods:** `readGraph(InputStream|File|URL, Graph)`
+
+**Writer Methods:** `writeGraph(OutputStream|File|URL, Graph)`
+
+**Configuration:**
+
+- `version(GraphSONVersion)`: GraphSON version (v1, v2, v3) - must match writer
+  version
+- `mapper(ObjectMapper)`: Custom JSON mapper for parsing/generation (Jackson
+  ObjectMapper)
+- `embedTypes(boolean)`: Include type information in serialization (default:
+  `false` for v1, `true` for v2/v3)
+- `includeNullProperties(boolean)`: Include null property values (default:
+  `false`)
+- `normalize(boolean)`: Normalize property keys (default: `false`)
+
+**Usage:**
+
+```java
+Graph graph = TinkerGraph.open();
+GraphSONReader reader = GraphSONReader.build()
+    .version(GraphSONVersion.V3_0)
+    .mapper(new ObjectMapper())
+    .create();
+reader.readGraph(new File("graph.json"), graph);
+
+GraphSONWriter writer = GraphSONWriter.build()
+    .version(GraphSONVersion.V3_0)
+    .embedTypes(true)
+    .includeNullProperties(false)
+    .create();
+writer.writeGraph(new File("graph.json"), graph);
+```
+
+## Version Compatibility
+
+**Important:** GraphSON reader and writer must use the same version for proper
+serialization/deserialization.
+
+**Compatibility Rules:** v1 reader can only read v1 files, v2 reader can only
+read v2 files, v3 reader can only read v3 files, version mismatch causes
+deserialization errors.
+
+**Best Practice:** Always specify the version explicitly when creating readers
+and writers.
+
+## GraphSON Structure
+
+GraphSON represents graph elements as JSON objects.
+
+### Vertex Representation
+
+**GraphSON v1:**
+
+```json
+{
+	"id": 1,
+	"label": "person",
+	"properties": {
+		"name": ["John"],
+		"age": [30]
+	}
+}
+```
+
+**GraphSON v2/v3 (with types):**
+
+```json
+{
+	"id": { "@type": "g:Int32", "@value": 1 },
+	"label": "person",
+	"properties": {
+		"name": [{ "@type": "g:String", "@value": "John" }],
+		"age": [{ "@type": "g:Int32", "@value": 30 }]
+	}
+}
+```
+
+### Edge Representation
+
+**GraphSON v1:**
+
+```json
+{
+	"id": 7,
+	"label": "knows",
+	"inV": 2,
+	"outV": 1,
+	"properties": {
+		"weight": 0.5
+	}
+}
+```
+
+**GraphSON v2/v3 (with types):**
+
+```json
+{
+	"id": { "@type": "g:Int64", "@value": 7 },
+	"label": "knows",
+	"inV": { "@type": "g:Int32", "@value": 2 },
+	"outV": { "@type": "g:Int32", "@value": 1 },
+	"properties": {
+		"weight": { "@type": "g:Double", "@value": 0.5 }
+	}
+}
+```
+
+### Property Representation
+
+**GraphSON v1:** Properties are simple JSON values, no type information
+embedded.
+
+**GraphSON v2/v3:** Properties can include type information. Format:
+`{"@type": "typeName", "@value": value}`. Type names follow TinkerPop type
+system (e.g., `g:String`, `g:Int32`, `g:Double`).
+
+### Meta-Properties (v2/v3 only)
+
+Meta-properties (properties on vertex properties) are supported. Represented as
+nested property structures:
+
+```json
+{
+	"properties": {
+		"name": [
+			{
+				"@type": "g:VertexProperty",
+				"@value": {
+					"id": { "@type": "g:Int64", "@value": 0 },
+					"value": { "@type": "g:String", "@value": "John" },
+					"properties": {
+						"created": { "@type": "g:Date", "@value": 1234567890 }
+					}
+				}
+			}
+		]
+	}
+}
+```
+
+## Type System
+
+GraphSON supports TinkerPop's type system through type embedding.
+
+**Supported Types:** Primitive Types (String, Integer, Long, Float, Double,
+Boolean), Date/Time Types (Date, Timestamp), Graph Elements (Vertex, Edge,
+VertexProperty, Property), Collection Types (List, Set, Map), Path Types (Path),
+Special Types (UUID, BigDecimal, BigInteger).
+
+**Type Embedding:** When `embedTypes` is `true`, types are embedded in JSON
+using `@type` and `@value` structure. Type names follow TinkerPop conventions
+(e.g., `g:String`, `g:Int32`). Enables proper type preservation during
+serialization/deserialization.
+
+## Configuration Best Practices
+
+**Reading:** Max Compatibility: `version(GraphSONVersion.V3_0)`, Custom JSON
+Parsing: `mapper(customMapper)` with custom ObjectMapper configuration.
+
+**Writing:** Network Transfer (Gremlin Server): `version(GraphSONVersion.V3_0)`,
+`embedTypes(true)`, `includeNullProperties(false)`. Human-Readable Output:
+`version(GraphSONVersion.V2_0)`, `embedTypes(true)`,
+`includeNullProperties(true)`, `normalize(true)`.
+
+**General Configuration:** See
+[TINKERPOP.md](TINKERPOP.md#general-configuration-best-practices) for general
+configuration best practices across all formats.
+
+## Error Handling
+
+**Format-Specific Issues:** Version mismatch (reader and writer versions must
+match), type mismatch (when `embedTypes` is inconsistent between reader/writer),
+invalid JSON (malformed JSON causes parsing errors), missing properties
+(properties may be omitted if `includeNullProperties` is false).
+
+**Format-Specific Best Practices:** Always specify version explicitly, use
+consistent configuration between reader and writer, validate JSON before
+parsing, handle missing properties gracefully.
+
+**General Error Handling:** See
+[TINKERPOP.md](TINKERPOP.md#general-error-handling-patterns) for common error
+handling patterns across all formats.
+
+## Performance Considerations
+
+**Format-Specific Optimization Tips:** Use GraphSON v3 for best performance, set
+`includeNullProperties(false)` to reduce output size, use `embedTypes(true)`
+only when type preservation is required, consider compression for large graphs,
+use streaming for very large graphs.
+
+**File Size:** More compact than GraphML. Typed format (v2/v3) is slightly
+larger than untyped (v1). Null properties increase file size if included.
+Compression can significantly reduce file size.
+
+**General Performance Considerations:** See
+[TINKERPOP.md](TINKERPOP.md#general-performance-considerations) for format
+comparison and general optimization tips.
+
+## Examples
+
+**Complete GraphSON Example (v3):**
+
+```json
+{
+	"vertices": [
+		{
+			"id": { "@type": "g:Int32", "@value": 1 },
+			"label": "person",
+			"properties": {
+				"name": [{ "@type": "g:String", "@value": "Alice" }],
+				"age": [{ "@type": "g:Int32", "@value": 30 }]
+			}
+		}
+	],
+	"edges": [
+		{
+			"id": { "@type": "g:Int64", "@value": 7 },
+			"label": "knows",
+			"inV": { "@type": "g:Int32", "@value": 2 },
+			"outV": { "@type": "g:Int32", "@value": 1 },
+			"properties": {
+				"weight": { "@type": "g:Double", "@value": 0.5 }
+			}
+		}
+	]
+}
+```
+
+**Reading and Writing:**
+
+```java
+Graph graph = TinkerGraph.open();
+Vertex alice = graph.addVertex(T.label, "person", "name", "Alice", "age", 30);
+Vertex bob = graph.addVertex(T.label, "person", "name", "Bob", "age", 25);
+alice.addEdge("knows", bob, "weight", 0.5);
+
+GraphSONWriter writer = GraphSONWriter.build()
+    .version(GraphSONVersion.V3_0)
+    .embedTypes(true)
+    .create();
+writer.writeGraph(new File("graph.json"), graph);
+
+Graph readGraph = TinkerGraph.open();
+GraphSONReader reader = GraphSONReader.build()
+    .version(GraphSONVersion.V3_0)
+    .create();
+reader.readGraph(new File("graph.json"), readGraph);
+```