Why Non-Interactive CLI is Essential for AI Coding Agent-Driven PuppyGraph Development

puppygraph-non-interactive-cli.md

Why Non-Interactive CLI is Essential for AI Coding Agent-Driven PuppyGraph Development

Based on the knowledge base documents, here's an analysis of why a comprehensive non-interactive CLI is crucial for AI agents working with PuppyGraph:

Current Limitation

The Existing CLI is Unusable by AI Agents:

From puppygraph-cli.md:

⚠️ NOTE FOR AI CODING AGENTS: This CLI is interactive-only (requires TTY) 
and NOT usable by AI agents. The CLI console commands (console, cypher-console, 
groovy) require human interaction and will fail with 'panic: no such device or 
address' when piped stdin.

This creates a fundamental gap in AI-driven workflows.

Why Non-Interactive CLI is Critical

1. Deterministic Execution from Natural Language

Human Input:

"Create a graph schema for a social network with users and friendships"

What AI Agent Needs to Do:

# Generate schema
puppygraph schema generate \
  --vertex users:id,name,email \
  --edge friendships:user_id->user_id \
  --output schema.json

# Validate schema
puppygraph schema validate schema.json

# Upload schema
puppygraph schema upload schema.json \
  --host localhost:8081 \
  --user puppygraph \
  --password puppygraph123

Current Workaround (Fragile):

# AI must write Python code instead
import json
schema = {...}  # Complex nested structure
with open('schema.json', 'w') as f:
    json.dump(schema, f)
# Then use curl command

2. Schema Design Assistance

Needed CLI Commands:

# Inspect data source
puppygraph inspect duckdb:///home/share/demo.db \
  --schema modern \
  --output analysis.json

# Output: Table structures, relationships, cardinalities
{
  "tables": {
    "person": {"columns": ["id", "name", "age"], "row_count": 6},
    "knows": {"columns": ["id", "from_id", "to_id"], "row_count": 6}
  },
  "suggested_vertices": ["person"],
  "suggested_edges": ["knows: person->person"]
}

# Generate schema from inspection
puppygraph schema generate \
  --from-inspection analysis.json \
  --mapping-strategy auto \
  --output schema.json

# AI can parse structured output and refine

Current Reality: AI must:

1. Write Python/bash to query DuckDB directly
2. Manually construct entire schema JSON
3. No validation until upload fails

3. Query Development & Testing

Needed Commands:

# Execute Gremlin query non-interactively
puppygraph query gremlin \
  --query "g.V().count()" \
  --host localhost:8182 \
  --format json

# Execute from file
puppygraph query gremlin \
  --file queries/analysis.groovy \
  --params '{"name": "marko"}' \
  --output results.json

# Cypher equivalent
puppygraph query cypher \
  --query "MATCH (p:person) RETURN count(p)" \
  --host localhost:7687 \
  --format json

# Validate query syntax without execution
puppygraph query validate \
  --language gremlin \
  --query "g.V().has('name', name).out()"

Current Reality:

# AI must write full Python scripts for every query
from gremlin_python.driver import client
gremlin_client = client.Client('ws://localhost:8182/gremlin', 'g')
try:
    result = gremlin_client.submit('g.V().count()').all().result()
    print(result[0])
finally:
    gremlin_client.close()

4. Error Diagnosis & Feedback Loop

Needed Commands:

# Check schema status
puppygraph schema status --verbose
# Output: Validation errors, missing tables, FK mismatches

# Test connectivity
puppygraph health check --all
# Output: Container, Gremlin, Cypher, data source status

# Explain query plan
puppygraph query explain \
  --language gremlin \
  --query "g.V().has('name', 'marko').out().out()"
# Output: Execution plan, estimated cost, optimization hints

Benefits for AI Agents:

• Structured error messages (parseable JSON)
• Actionable diagnostics
• Faster iteration on schema/query refinement

5. Complete AI Workflow Example

Human Request:

"Analyze the Modern graph dataset and find the most connected person"

AI Agent Workflow with Proper CLI:

# 1. Inspect data
puppygraph inspect duckdb:///home/share/demo.db \
  --schema modern --format json > inspection.json

# AI parses inspection.json to understand structure

# 2. Generate schema
puppygraph schema generate \
  --from-inspection inspection.json \
  --output schema.json

# 3. Validate schema
puppygraph schema validate schema.json --strict
# Returns: exit code 0 + validation report

# 4. Upload schema
puppygraph schema upload schema.json \
  --host localhost:8081 \
  --wait-ready

# 5. Execute query
puppygraph query gremlin \
  --query "g.V().hasLabel('person').project('name','connections').by('name').by(bothE().count()).order().by(select('connections'), desc).limit(1)" \
  --format json > results.json

# 6. AI parses results.json and responds to human

Current Reality (Manual Script Writing):

• 5+ Python files
• Complex error handling
• No standardized output formats
• Brittle connection management

Essential CLI Features for AI Agents

Schema Management

puppygraph schema generate [options]
puppygraph schema validate <file>
puppygraph schema upload <file>
puppygraph schema download --output <file>
puppygraph schema diff <file1> <file2>
puppygraph schema migrate <old> <new>

Data Inspection

puppygraph inspect <jdbc-uri> [options]
puppygraph analyze <jdbc-uri> --recommend-schema

Query Execution

puppygraph query gremlin --query <query> [options]
puppygraph query cypher --query <query> [options]
puppygraph query validate --language <lang> --query <query>
puppygraph query explain --language <lang> --query <query>
puppygraph query batch --file <queries.txt>

Diagnostics

puppygraph health check [--all|--gremlin|--cypher|--data]
puppygraph debug connection --protocol <gremlin|cypher>
puppygraph debug schema --verbose
puppygraph logs --tail 100 --filter error

Data Operations

puppygraph data load <file> --table <table> --schema <schema>
puppygraph data export --query <query> --format csv
puppygraph data stats --vertex <label>|--edge <label>

Key Design Principles

1. Structured Output

# Always support --format json|yaml|table
puppygraph query gremlin --query "g.V().count()" --format json
{"result": [6], "execution_time_ms": 45}

2. Exit Codes

puppygraph schema validate schema.json
# Exit 0: valid
# Exit 1: invalid (with error details in stderr)

3. Composability

# Pipeline-friendly
puppygraph inspect duckdb://... | \
  puppygraph schema generate --from-stdin | \
  puppygraph schema validate --stdin

4. Comprehensive Help

puppygraph --help
puppygraph query --help
puppygraph query gremlin --help
# Each command documents: purpose, arguments, options, examples

5. Safe Defaults

# Read credentials from environment
export PUPPYGRAPH_HOST=localhost:8081
export PUPPYGRAPH_USER=puppygraph
export PUPPYGRAPH_PASSWORD=puppygraph123

puppygraph schema upload schema.json
# No need to repeat --host, --user, --password

Impact on AI-Driven Development

Aspect	Current (Python/curl)	With Proper CLI
Schema Design	Manual JSON construction	schema generate from inspection
Validation	Upload & pray	schema validate before upload
Query Testing	Write Python script	Single command execution
Error Handling	Parse exception strings	Structured JSON errors
Iteration Speed	5-10 minutes per cycle	30 seconds per cycle
Code Complexity	100+ lines Python	3-5 CLI commands
Reliability	Connection issues common	Built-in retry/timeout logic

Conclusion

A non-interactive CLI transforms PuppyGraph from a human-interactive tool to an AI-automation-friendly platform. It enables:

1. Direct translation of natural language to executable commands
2. Rapid iteration on schema and query development
3. Structured feedback for AI decision-making
4. Composable workflows via standard Unix patterns
5. Reduced complexity (commands vs. code)

Current State: AI agents must write elaborate Python scripts for every operation.

With CLI: AI agents execute deterministic commands with predictable outputs, enabling true natural-language-to-graph-query automation.

This is the difference between:

• "Write a Python script that connects to PuppyGraph and..." (current)
• "Find the most connected person in the Modern graph" (AI executes: puppygraph query gremlin --query "..." --format json)

The CLI becomes the executable interface that bridges human intent and graph analytics at machine speed.