{"id":49225288,"url":"https://github.com/neo4j-labs/create-context-graph","last_synced_at":"2026-04-24T06:33:52.394Z","repository":{"id":346792366,"uuid":"1188887217","full_name":"neo4j-labs/create-context-graph","owner":"neo4j-labs","description":"AI agents with graph based reasoning memory, scaffolded in seconds","archived":false,"fork":false,"pushed_at":"2026-04-15T01:10:22.000Z","size":9141,"stargazers_count":486,"open_issues_count":2,"forks_count":53,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-15T02:33:22.382Z","etag":null,"topics":["agent-memory","context-graph","neo4j"],"latest_commit_sha":null,"homepage":"https://create-context-graph.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neo4j-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T18:04:44.000Z","updated_at":"2026-04-15T01:10:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/neo4j-labs/create-context-graph","commit_stats":null,"previous_names":["neo4j-labs/create-context-graph"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/neo4j-labs/create-context-graph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j-labs%2Fcreate-context-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j-labs%2Fcreate-context-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j-labs%2Fcreate-context-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j-labs%2Fcreate-context-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neo4j-labs","download_url":"https://codeload.github.com/neo4j-labs/create-context-graph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j-labs%2Fcreate-context-graph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32212807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","context-graph","neo4j"],"created_at":"2026-04-24T06:33:50.500Z","updated_at":"2026-04-24T06:33:52.387Z","avatar_url":"https://github.com/neo4j-labs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Create Context Graph\n\n[![Neo4j Labs](https://img.shields.io/badge/Neo4j_Labs-blue?logo=neo4j)](https://neo4j.com/labs/)\n[![Docs](https://img.shields.io/badge/docs-docusaurus-green)](https://create-context-graph.dev/)\n\n\u003e **Neo4j Labs Project** — This project is part of [Neo4j Labs](https://neo4j.com/labs/). It is maintained by Neo4j staff and the community, but not officially supported. For help, use [GitHub Issues](https://github.com/neo4j-labs/create-context-graph/issues) or the [Neo4j Community Forum](https://community.neo4j.com/).\n\nInteractive CLI scaffolding tool that generates fully-functional, domain-specific context graph applications. Pick your industry domain, pick your agent framework, and get a complete full-stack app in under 5 minutes.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/static/img/app-three-panel.png\" alt=\"Generated app: chat interface, graph visualization, and document browser\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n```bash\n# Python\nuvx create-context-graph\n\n# Node.js\nnpx create-context-graph\n\n# Non-interactive (PROJECT_NAME is optional — auto-generates slug from domain+framework)\nuvx create-context-graph --domain healthcare --framework pydanticai --demo-data\n```\n\n## What It Does\n\nCreate Context Graph walks you through an interactive wizard and generates a complete project:\n\n- **FastAPI backend** with an AI agent configured for your domain, powered by [neo4j-agent-memory](https://github.com/neo4j-labs/agent-memory) v0.1.0 for multi-turn conversations with automatic entity extraction and preference detection\n- **Next.js + Chakra UI v3 frontend** with streaming chat (Server-Sent Events), real-time tool call visualization (Timeline with live spinners), interactive graph visualization (schema view, double-click expand, drag/zoom, property panel), entity detail panel, document browser, and decision trace viewer\n- **Neo4j schema** with domain-specific constraints, indexes, and GDS projections\n- **Rich demo data** — LLM-generated entities, relationships, professional documents (discharge summaries, trade confirmations, lab reports), and multi-step decision traces\n- **SaaS data import** — connect GitHub, Slack, Gmail, Jira, Notion, Google Calendar, or Salesforce\n- **Custom domains** — describe your domain in plain English and the LLM generates a complete ontology\n- **Domain-specific agent tools** with Cypher queries tailored to your industry\n- **MCP server for Claude Desktop** — optionally generates an MCP server config so Claude Desktop can query the same knowledge graph (`--with-mcp`)\n\n```\n  Creating context graph application...\n\n  Domain:     Wildlife Management\n  Framework:  PydanticAI\n  Data:       Demo (synthetic)\n  Neo4j:      Docker (neo4j://localhost:7687)\n\n  [1/6] Generating domain ontology...          ✓\n  [2/6] Creating project scaffold...           ✓\n  [3/6] Configuring agent tools \u0026 system prompt...  ✓\n  [4/6] Generating synthetic documents (25 docs)... ✓\n  [5/6] Writing fixture data...                ✓\n  [6/6] Bundling project...                    ✓\n\n  Done! Your context graph app is ready.\n\n  cd my-app\n  make install \u0026\u0026 make start\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.11+ (with [uv](https://docs.astral.sh/uv/) recommended)\n- Node.js 18+ (for the frontend)\n- Neo4j 5+ (Docker, Aura, or local install)\n\n### 1. Create a project\n\n```bash\nuvx create-context-graph\n```\n\nThe interactive wizard will guide you through selecting a domain, framework, and Neo4j connection.\n\nOr skip the wizard with flags:\n\n```bash\nuvx create-context-graph my-app \\\n  --domain financial-services \\\n  --framework pydanticai \\\n  --demo-data\n\n# Custom domain from description\nuvx create-context-graph my-app \\\n  --custom-domain \"veterinary clinic management\" \\\n  --framework pydanticai \\\n  --anthropic-api-key $ANTHROPIC_API_KEY \\\n  --demo-data\n\n# Import from SaaS services\nuvx create-context-graph my-app \\\n  --domain personal-knowledge \\\n  --framework pydanticai \\\n  --connector github \\\n  --connector slack\n\n# With MCP server for Claude Desktop\nuvx create-context-graph my-app \\\n  --domain healthcare \\\n  --framework pydanticai \\\n  --demo-data \\\n  --with-mcp\n```\n\n### 2. Start the app\n\nThe wizard offers four Neo4j connection options:\n\n| Option | Command | Description |\n|--------|---------|-------------|\n| **Neo4j Aura** (cloud) | *(no start needed)* | Free cloud database — import your `.env` from [console.neo4j.io](https://console.neo4j.io) |\n| **neo4j-local** | `make neo4j-start` | Lightweight local Neo4j, no Docker required (needs Node.js) |\n| **Docker** | `make docker-up` | Full Neo4j via Docker Compose |\n| **Existing** | *(no start needed)* | Connect to any running Neo4j instance |\n\n```bash\ncd my-app\nmake install       # Install backend + frontend dependencies\nmake neo4j-start   # Start Neo4j (if using neo4j-local)\n# OR: make docker-up  # Start Neo4j (if using Docker)\nmake seed          # Seed sample data into Neo4j\nmake start         # Start backend (port 8000) + frontend (port 3000)\n```\n\n### 3. Explore\n\n- **Frontend:** http://localhost:3000 — Chat with the AI agent, explore the knowledge graph\n- **Backend API:** http://localhost:8000/docs — FastAPI auto-generated docs\n- **Neo4j Browser:** http://localhost:7474 — Query the graph directly\n\n## Supported Domains\n\n22 industry domains, each with a purpose-built ontology, sample data, agent tools, and demo scenarios:\n\n| Domain | Key Entities | Domain | Key Entities |\n|--------|-------------|--------|-------------|\n| Financial Services | Account, Transaction, Decision, Policy | Real Estate | Property, Listing, Agent, Inspection |\n| Healthcare | Patient, Provider, Diagnosis, Treatment | Vacation \u0026 Hospitality | Resort, Booking, Guest, Activity |\n| Retail \u0026 E-Commerce | Customer, Product, Order, Review | Oil \u0026 Gas | Well, Reservoir, Equipment, Permit |\n| Manufacturing | Machine, Part, WorkOrder, Supplier | Data Journalism | Source, Story, Claim, Investigation |\n| Scientific Research | Researcher, Paper, Dataset, Grant | Trip Planning | Destination, Hotel, Activity, Itinerary |\n| GenAI / LLM Ops | Model, Experiment, Prompt, Evaluation | GIS \u0026 Cartography | Feature, Layer, Survey, Boundary |\n| Agent Memory | Agent, Conversation, Memory, ToolCall | Wildlife Management | Species, Sighting, Habitat, Camera |\n| Gaming | Player, Character, Quest, Guild | Conservation | Site, Species, Program, Funding |\n| Personal Knowledge | Note, Contact, Project, Topic | Golf \u0026 Sports Mgmt | Course, Player, Round, Tournament |\n| Digital Twin | Asset, Sensor, Reading, Alert | Software Engineering | Repository, Issue, PR, Deployment |\n| Product Management | Feature, Epic, UserPersona, Metric | Hospitality | Hotel, Room, Reservation, Service |\n\n```bash\n# List all available domains\ncreate-context-graph --list-domains\n```\n\n**Custom domains:** Don't see your industry? Select \"Custom (describe your domain)\" in the wizard or use `--custom-domain \"your description\"`. The LLM generates a complete ontology with entity types, relationships, agent tools, and more.\n\n## SaaS Data Connectors\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/static/img/connector-data-flow.png\" alt=\"SaaS connector data flow into Neo4j knowledge graph\" width=\"700\" /\u003e\n\u003c/p\u003e\n\nImport real data from your existing tools instead of (or in addition to) synthetic demo data:\n\n| Service | What's Imported | Auth |\n|---------|----------------|------|\n| **GitHub** | Issues, PRs, commits, contributors | Personal access token |\n| **Notion** | Pages, databases, users | Integration token |\n| **Jira** | Issues, sprints, users | API token |\n| **Slack** | Channel messages, threads, users | Bot OAuth token |\n| **Gmail** | Emails (last 30 days) | Google Workspace CLI or OAuth2 |\n| **Google Calendar** | Events, attendees (last 90 days) | Google Workspace CLI or OAuth2 |\n| **Salesforce** | Accounts, contacts, opportunities | Username/password |\n| **Linear** | Issues, projects, cycles, teams, users, labels, comments, milestones, initiatives, attachments + decision traces from history | Personal API key |\n| **Google Workspace** | Drive files, comment threads (as decision traces), revisions, Drive Activity, Calendar events, Gmail metadata | Google OAuth 2.0 |\n| **Claude Code** | Session history, messages, tool calls, files, decisions, preferences, errors | None (local files) |\n| **Claude AI** | Conversations, messages, tool calls, thinking traces from Claude AI web/app export | None (local file) |\n| **ChatGPT** | Conversations, messages, tool results from ChatGPT data export | None (local file) |\n\nThe **Google Workspace connector** extracts resolved comment threads from Google Docs as first-class decision traces — capturing the question, deliberation, resolution, and participants. Combined with Linear, it provides the full decision lifecycle: from meeting discussion to code execution.\n\nThe **Claude Code connector** reads your local session history from `~/.claude/projects/` — no API keys needed. It extracts decision traces from user corrections and error-resolution cycles, identifies developer preferences from explicit statements and behavioral patterns, and automatically redacts secrets before storage.\n\nThe **Claude AI** and **ChatGPT** connectors import your conversation exports directly from the official data export features. Export your data from Settings, pass the `.zip` file to the CLI with `--import-type claude-ai` or `--import-type chatgpt`, and get a fully populated context graph from your real conversations — no API keys needed.\n\nConnectors run at scaffold time to populate initial data. They're also generated into your project so you can re-import with `make import`:\n\n```bash\ncd my-app\nmake import            # Re-import from connected services\nmake import-and-seed   # Import and seed into Neo4j\n```\n\n## Agent Frameworks\n\nSelect your preferred agent framework at project creation time:\n\n| Framework | Description |\n|-----------|-------------|\n| **PydanticAI** | Structured tool definitions with Pydantic models and `RunContext` | Full streaming | `ANTHROPIC_API_KEY` |\n| **Claude Agent SDK** | Anthropic tool-use with agentic loop | Full streaming | `ANTHROPIC_API_KEY` |\n| **OpenAI Agents SDK** | `@function_tool` decorators with `Runner.run()` | Full streaming | `OPENAI_API_KEY` |\n| **LangGraph** | Stateful graph-based agent workflow with `create_react_agent()` | Full streaming | `ANTHROPIC_API_KEY` |\n| **CrewAI** | Multi-agent crew with role-based tools | Tool streaming | `ANTHROPIC_API_KEY` |\n| **Strands** | Tool-use agents with Anthropic model | Tool streaming | `ANTHROPIC_API_KEY` |\n| **Google ADK** | Gemini agents with `FunctionTool` calling | Full streaming | `GOOGLE_API_KEY` |\n| **Anthropic Tools** | Modular tool registry with Anthropic API agentic loop | Full streaming | `ANTHROPIC_API_KEY` |\n\nAll frameworks share the same FastAPI HTTP layer, Neo4j client, and frontend. Only the agent implementation differs. \"Full streaming\" means token-by-token text + real-time tool calls. \"Tool streaming\" means real-time tool calls with text delivered at the end.\n\n\u003e **Note:** Conversation memory uses local sentence-transformers embeddings by default — no `OPENAI_API_KEY` required. If you set `OPENAI_API_KEY` in your `.env`, it will automatically upgrade to OpenAI embeddings.\n\n## Generated Project Structure\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/static/img/ontology-pipeline.png\" alt=\"From domain YAML through Jinja2 templates to generated code\" width=\"750\" /\u003e\n\u003c/p\u003e\n\nA single domain YAML drives the entire generated application — schema, models, agent tools, and visualization — through the Jinja2 template engine.\n\n```\nmy-app/\n├── backend/\n│   ├── app/\n│   │   ├── main.py                # FastAPI application\n│   │   ├── agent.py               # AI agent (framework-specific)\n│   │   ├── config.py              # Settings from .env\n│   │   ├── routes.py              # REST API endpoints\n│   │   ├── models.py              # Pydantic models (from ontology)\n│   │   ├── context_graph_client.py # Neo4j CRUD operations\n│   │   ├── memory.py              # Memory integration (MemoryIntegration)\n│   │   ├── gds_client.py          # Graph Data Science algorithms\n│   │   ├── vector_client.py       # Vector search\n│   │   └── connectors/            # SaaS connectors (if selected)\n│   ├── scripts/\n│   │   ├── generate_data.py       # Data seeding script\n│   │   └── import_data.py         # SaaS import script (if connectors selected)\n│   └── pyproject.toml\n├── frontend/\n│   ├── app/                       # Next.js pages\n│   ├── components/\n│   │   ├── ChatInterface.tsx      # Streaming AI chat (SSE) with real-time tool calls + graph data flow\n│   │   ├── ContextGraphView.tsx   # Interactive NVL graph (schema view, expand, drag/zoom, properties)\n│   │   ├── DecisionTracePanel.tsx  # Reasoning trace viewer with step details\n│   │   ├── DocumentBrowser.tsx    # Document browser with template filtering\n│   │   └── Provider.tsx           # Chakra UI v3 provider\n│   ├── lib/config.ts              # Domain configuration\n│   ├── theme/index.ts             # Chakra theme with domain colors\n│   └── package.json\n├── cypher/\n│   ├── schema.cypher              # Constraints \u0026 indexes\n│   └── gds_projections.cypher     # GDS algorithm config\n├── data/\n│   ├── ontology.yaml              # Domain ontology definition\n│   └── fixtures.json              # Pre-generated sample data\n├── .env                           # Neo4j + API key configuration\n├── .env.example                   # Configuration template (tracked in git)\n├── .dockerignore                  # Docker build context exclusions\n├── docker-compose.yml             # Local Neo4j instance (Docker mode only)\n├── Makefile                       # start, seed, reset, install, test, test-connection, lint\n├── mcp/                           # MCP server config (only if --with-mcp)\n└── README.md                      # Domain-specific documentation (with framework docs + troubleshooting)\n```\n\n## CLI Reference\n\n```bash\ncreate-context-graph [PROJECT_NAME] [OPTIONS]\n\nArguments:\n  PROJECT_NAME              Project name (optional — auto-generated from domain+framework if omitted)\n\nOptions:\n  --domain TEXT             Domain ID (e.g., healthcare, gaming)\n  --framework TEXT          Agent framework (pydanticai, claude-agent-sdk, openai-agents, langgraph, crewai, strands, google-adk, anthropic-tools)\n  --demo-data               Generate synthetic demo data\n  --custom-domain TEXT      Generate custom domain from description (requires --anthropic-api-key)\n  --connector TEXT          SaaS connector to enable; repeatable (github, slack, jira, notion, gmail, gcal, salesforce, linear, google-workspace, claude-code, claude-ai, chatgpt)\n  --import-type TEXT        Chat history import: claude-ai or chatgpt (requires --import-file)\n  --import-file PATH        Path to chat export file (.zip, .json, .jsonl)\n  --import-depth TEXT       Import extraction depth: fast (default) or deep\n  --import-filter-after TEXT Only import conversations after this date (ISO 8601)\n  --import-filter-before TEXT Only import conversations before this date (ISO 8601)\n  --import-filter-title TEXT Only import conversations matching title pattern (regex)\n  --import-max-conversations INT Max conversations to import, 0=all (default: 0)\n  --linear-api-key TEXT    Linear API key (required for --connector linear) [env: LINEAR_API_KEY]\n  --linear-team TEXT       Linear team key to filter import (e.g., ENG) [env: LINEAR_TEAM]\n  --gws-folder-id TEXT     Google Drive folder ID to scope import [env: GWS_FOLDER_ID]\n  --gws-include-comments / --gws-no-comments  Import comment threads (default: on)\n  --gws-include-revisions / --gws-no-revisions  Import revision history (default: on)\n  --gws-include-activity / --gws-no-activity  Import Drive Activity (default: on)\n  --gws-include-calendar   Import Calendar events (default: off)\n  --gws-include-gmail      Import Gmail thread metadata (default: off)\n  --gws-since TEXT         Import data since date (ISO format, default: 90 days ago)\n  --gws-mime-types TEXT    MIME types to include (default: docs,sheets,slides)\n  --gws-max-files INT      Maximum files to import (default: 500)\n  --claude-code-scope TEXT Import current project or all (default: current)\n  --claude-code-project TEXT Explicit project path to import sessions for\n  --claude-code-since TEXT Import sessions since date (ISO format)\n  --claude-code-max-sessions INT Max sessions to import, 0=all (default: 0)\n  --claude-code-content TEXT Content mode: truncated, full, none (default: truncated)\n  --with-mcp                Generate MCP server configuration for Claude Desktop\n  --mcp-profile TEXT        MCP tool profile: core (6 tools) or extended (16 tools, default)\n  --session-strategy TEXT   Memory session strategy: per_conversation (default), per_day, persistent\n  --auto-extract/--no-auto-extract  Auto-extract entities from messages (default: on)\n  --auto-preferences/--no-auto-preferences  Auto-detect user preferences (default: on)\n  --ingest                  Ingest data into Neo4j after generation\n  --neo4j-uri TEXT          Neo4j connection URI [env: NEO4J_URI]\n  --neo4j-username TEXT     Neo4j username [env: NEO4J_USERNAME]\n  --neo4j-password TEXT     Neo4j password [env: NEO4J_PASSWORD]\n  --neo4j-aura-env PATH    Path to Neo4j Aura .env file with credentials\n  --neo4j-local             Use @johnymontana/neo4j-local for local Neo4j (no Docker)\n  --anthropic-api-key TEXT  Anthropic API key for LLM generation [env: ANTHROPIC_API_KEY]\n  --openai-api-key TEXT    OpenAI API key for LLM generation [env: OPENAI_API_KEY]\n  --google-api-key TEXT    Google/Gemini API key (required for google-adk) [env: GOOGLE_API_KEY]\n  --output-dir PATH         Output directory (default: ./\u003cproject-name\u003e)\n  --demo                    Shortcut for --reset-database --demo-data --ingest\n  --reset-database          Clear all Neo4j data before ingesting\n  --dry-run                 Preview what would be generated without creating files\n  --verbose                 Enable verbose debug output\n  --list-domains            List available domains and exit\n  --version                 Show version and exit\n  --help                    Show help and exit\n```\n\n## Context Graph Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/static/img/architecture-overview.png\" alt=\"Architecture: generation pipeline and runtime components\" width=\"800\" /\u003e\n\u003c/p\u003e\n\nEvery generated app demonstrates the three-memory-type architecture from [neo4j-agent-memory](https://github.com/neo4j-labs/agent-memory):\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/static/img/memory-architecture.png\" alt=\"Three memory types: short-term, long-term, and reasoning memory in Neo4j\" width=\"700\" /\u003e\n\u003c/p\u003e\n\n- **Short-term memory** — Conversation history and document content stored as messages\n- **Long-term memory** — Entity knowledge graph built on the POLE+O model (Person, Organization, Location, Event, Object)\n- **Reasoning memory** — Decision traces with full provenance: thought chains, tool calls, causal relationships\n\nThis is what makes context graphs different from simple RAG — the agent doesn't just retrieve text, it reasons over a structured knowledge graph with full decision traceability.\n\nWith `--with-mcp`, the generated project also includes an MCP server configuration that connects Claude Desktop to the same knowledge graph. This dual-interface architecture means the web app and Claude Desktop share one context graph — entities, conversations, and reasoning traces are available everywhere.\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/neo4j-labs/create-context-graph.git\ncd create-context-graph\nuv venv \u0026\u0026 uv pip install -e \".[dev]\"\n\n# Run tests (no Neo4j or API keys required)\nsource .venv/bin/activate\npytest tests/ -v               # Fast: 1,053 tests\npytest tests/ -v --slow        # Full: 1,259 tests (includes domain x framework matrix + perf + generated project tests)\npytest tests/ --integration    # Integration tests (requires running Neo4j)\n\n# Test a specific scaffold\ncreate-context-graph /tmp/test-app --domain software-engineering --framework pydanticai --demo-data\n```\n\n### Makefile Targets\n\n| Target | Description | Requirements |\n|--------|-------------|--------------|\n| `make test` | Run fast unit tests (1,053 tests) | None |\n| `make test-slow` | Full suite including matrix + perf + generated project tests (1,259 tests) | None |\n| `make test-matrix` | Domain × framework matrix only (176 combos) | None |\n| `make test-coverage` | Tests with HTML coverage report | None |\n| `make smoke-test` | E2E smoke tests for 3 key frameworks | Neo4j + LLM API keys |\n| `make lint` | Run ruff linter | ruff |\n| `make scaffold` | Scaffold a test project to `/tmp/test-scaffold` | None |\n| `make build` | Build Python package (sdist + wheel) | None |\n| `make docs` | Start Docusaurus dev server | Node.js |\n\n### E2E Smoke Tests\n\nThe smoke tests scaffold a real project, install dependencies, start the backend, and send chat prompts to verify the full pipeline works end-to-end. They test the 3 frameworks that had critical bug fixes in v0.5.1:\n\n```bash\n# Run all 3 smoke tests (requires Neo4j + at least one LLM API key)\nmake smoke-test\n\n# Or run individual framework tests directly\npython scripts/e2e_smoke_test.py --domain financial-services --framework pydanticai --quick\npython scripts/e2e_smoke_test.py --domain real-estate --framework google-adk --quick\npython scripts/e2e_smoke_test.py --domain trip-planning --framework strands --quick\n\n# Test all 22 domains with one framework\npython scripts/e2e_smoke_test.py --all-domains --framework pydanticai --quick\n\n# Full mode (all prompts per scenario, not just first)\npython scripts/e2e_smoke_test.py --domain healthcare --framework claude-agent-sdk\n```\n\n**Required environment variables:**\n- `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD` — Neo4j connection (Aura, Docker, or local)\n- `ANTHROPIC_API_KEY` — for Claude-based frameworks (PydanticAI, Claude Agent SDK, Anthropic Tools, Strands, CrewAI)\n- `OPENAI_API_KEY` — for OpenAI-based frameworks (OpenAI Agents, LangGraph)\n- `GOOGLE_API_KEY` — for Google ADK (Gemini)\n\n### CI Pipeline\n\nGitHub Actions (`.github/workflows/ci.yml`) runs automatically:\n\n| Job | Trigger | Description |\n|-----|---------|-------------|\n| **test** | All pushes + PRs | Unit tests on Python 3.11 and 3.12 (1,053 tests including security, doc snippets, frontend logic) |\n| **lint** | All pushes + PRs | Ruff linter on `src/` and `tests/` |\n| **matrix** | Push to `main` only | Full suite + 176 domain × framework matrix + perf + generated project tests (1,259 tests) |\n| **smoke-test** | Push to `main` only | Neo4j integration tests + E2E for all 8 frameworks (scaffold → install → start → chat) |\n\nThe smoke-test CI job is gated behind a `SMOKE_TESTS_ENABLED` repository variable. To enable it:\n\n1. Go to **Settings → Variables → Repository variables** and add `SMOKE_TESTS_ENABLED` = `true`\n2. Go to **Settings → Secrets → Repository secrets** and add:\n   - `NEO4J_URI` — e.g., `neo4j+s://xxxxx.databases.neo4j.io`\n   - `NEO4J_USERNAME`\n   - `NEO4J_PASSWORD`\n   - `ANTHROPIC_API_KEY`\n   - `OPENAI_API_KEY`\n   - `GOOGLE_API_KEY`\n\nThe smoke-test job uses `fail-fast: false` so one framework failure doesn't block the others, and it only runs after the unit test job passes.\n\n\nThe npm package is a thin wrapper that delegates to the Python CLI via `uvx`, `pipx`, or `python3 -m`. It requires Python 3.11+ to be installed.\n\n### Automated Publishing (GitHub Actions)\n\nBoth packages are published automatically when you push a version tag:\n\n```bash\n# 1. Update version in pyproject.toml and npm-wrapper/package.json\n# 2. Commit the version bump\n# 3. Tag and push\ngit tag v0.1.0\ngit push origin v0.1.0\n```\n\nThis triggers a GitHub Actions workflow, `release.yml` with jobs:\n- **publish-pypi** — Builds and publishes to PyPI\n- **publish-npm** — Publishes the npm wrapper to npmjs.com\nBoth use trusted publishing/OIDC.\n\n### Version Bumping\n\nBoth packages must use the same version. Update in two places:\n\n1. `pyproject.toml` → `version = \"X.Y.Z\"`\n2. `npm-wrapper/package.json` → `\"version\": \"X.Y.Z\"`\n\nNote: a job called `validate-version-consistency` in `release.yml` ensures that the correct versions exist in both places.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneo4j-labs%2Fcreate-context-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneo4j-labs%2Fcreate-context-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneo4j-labs%2Fcreate-context-graph/lists"}