diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..b61d4251 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,54 @@ +--- +name: Bug Report +about: Create a report to help us improve Graphiti +title: '[BUG] ' +labels: bug +assignees: '' +--- + +## Bug Description +A clear and concise description of what the bug is. + +## Steps to Reproduce +Provide a minimal code example that reproduces the issue: + +```python +# Your code here +``` + +## Expected Behavior +A clear and concise description of what you expected to happen. + +## Actual Behavior +A clear and concise description of what actually happened. + +## Environment +- **Graphiti Version**: [e.g. 0.15.1] +- **Python Version**: [e.g. 3.11.5] +- **Operating System**: [e.g. macOS 14.0, Ubuntu 22.04] +- **Database Backend**: [e.g. Neo4j 5.26, FalkorDB 1.1.2] +- **LLM Provider & Model**: [e.g. OpenAI gpt-4.1, Anthropic claude-4-sonnet, Google gemini-2.5-flash] + +## Installation Method +- [ ] pip install +- [ ] uv add +- [ ] Development installation (git clone) + +## Error Messages/Traceback +``` +Paste the full error message and traceback here +``` + +## Configuration +```python +# Relevant configuration or initialization code +``` + +## Additional Context +- Does this happen consistently or intermittently? +- Which component are you using? (core library, REST server, MCP server) +- Any recent changes to your environment? +- Related issues or similar problems you've encountered? + +## Possible Solution +If you have ideas about what might be causing the issue or how to fix it, please share them here. \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..1139318e --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,32 @@ +## Summary +Brief description of the changes in this PR. + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Performance improvement +- [ ] Documentation/Tests + +## Objective +**For new features and performance improvements:** Clearly describe the objective and rationale for this change. + +## Testing +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] All existing tests pass + +## Breaking Changes +- [ ] This PR contains breaking changes + +If this is a breaking change, describe: +- What functionality is affected +- Migration path for existing users + +## Checklist +- [ ] Code follows project style guidelines (`make lint` passes) +- [ ] Self-review completed +- [ ] Documentation updated where necessary +- [ ] No secrets or sensitive information committed + +## Related Issues +Closes #[issue number] \ No newline at end of file diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml index 19bea375..0622abfa 100644 --- a/.github/workflows/cla.yml +++ b/.github/workflows/cla.yml @@ -28,7 +28,7 @@ jobs: path-to-document: "https://github.com/getzep/graphiti/blob/main/Zep-CLA.md" # e.g. a CLA or a DCO document # branch should not be protected unless a personal PAT is used branch: "main" - allowlist: paul-paliychuk,prasmussen15,danielchalef,dependabot[bot],ellipsis-dev + allowlist: paul-paliychuk,prasmussen15,danielchalef,dependabot[bot],ellipsis-dev,Claude[bot] # the followings are the optional inputs - If the optional inputs are not given, then default values will be taken #remote-organization-name: enter the remote organization name where the signatures should be stored (Default is storing the signatures in the same repository) diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml new file mode 100644 index 00000000..d3e75ada --- /dev/null +++ b/.github/workflows/claude-code-review.yml @@ -0,0 +1,78 @@ +name: Claude Code Review + +on: + pull_request: + types: [opened, synchronize] + # Optional: Only run on specific file changes + # paths: + # - "src/**/*.ts" + # - "src/**/*.tsx" + # - "src/**/*.js" + # - "src/**/*.jsx" + +jobs: + claude-review: + # Optional: Filter by PR author + # if: | + # github.event.pull_request.user.login == 'external-contributor' || + # github.event.pull_request.user.login == 'new-developer' || + # github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' + + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + issues: read + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Run Claude Code Review + id: claude-review + uses: anthropics/claude-code-action@beta + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + + # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4) + # model: "claude-opus-4-20250514" + + # Direct prompt for automated review (no @claude mention needed) + direct_prompt: | + Please review this pull request and provide feedback on: + - Code quality and best practices + - Potential bugs or issues + - Performance considerations + - Security concerns + - Test coverage + + Be constructive and helpful in your feedback. + + # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR + # use_sticky_comment: true + + # Optional: Customize review based on file types + # direct_prompt: | + # Review this PR focusing on: + # - For TypeScript files: Type safety and proper interface usage + # - For API endpoints: Security, input validation, and error handling + # - For React components: Performance, accessibility, and best practices + # - For tests: Coverage, edge cases, and test quality + + # Optional: Different prompts for different authors + # direct_prompt: | + # ${{ github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' && + # 'Welcome! Please review this PR from a first-time contributor. Be encouraging and provide detailed explanations for any suggestions.' || + # 'Please provide a thorough code review focusing on our coding standards and best practices.' }} + + # Optional: Add specific tools for running tests or linting + # allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck)" + + # Optional: Skip review for certain conditions + # if: | + # !contains(github.event.pull_request.title, '[skip-review]') && + # !contains(github.event.pull_request.title, '[WIP]') + diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml new file mode 100644 index 00000000..04c611e9 --- /dev/null +++ b/.github/workflows/claude.yml @@ -0,0 +1,64 @@ +name: Claude Code + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + issues: write + id-token: write + actions: read # Required for Claude to read CI results on PRs + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@beta + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + + # This is an optional setting that allows Claude to read CI results on PRs + additional_permissions: | + actions: read + + # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4) + # model: "claude-opus-4-20250514" + + # Optional: Customize the trigger phrase (default: @claude) + # trigger_phrase: "/claude" + + # Optional: Trigger when specific user is assigned to an issue + # assignee_trigger: "claude-bot" + + # Optional: Allow Claude to run specific commands + # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)" + + # Optional: Add custom instructions for Claude to customize its behavior for your project + # custom_instructions: | + # Follow our coding standards + # Ensure all new code has tests + # Use TypeScript for new files + + # Optional: Custom environment variables for Claude + # claude_env: | + # NODE_ENV: test + diff --git a/CLAUDE.md b/CLAUDE.md index d5c8475a..7806eb3b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,7 @@ uv sync --extra dev # Format code (ruff import sorting + formatting) make format -# Lint code (ruff + mypy type checking) +# Lint code (ruff + pyright type checking) make lint # Run tests @@ -111,7 +111,8 @@ docker-compose up - Use Ruff for formatting and linting (configured in pyproject.toml) - Line length: 100 characters - Quote style: single quotes -- Type checking with MyPy is enforced +- Type checking with Pyright is enforced +- Main project uses `typeCheckingMode = "basic"`, server uses `typeCheckingMode = "standard"` ### Testing Requirements @@ -130,4 +131,4 @@ When working with the MCP server, follow the patterns established in `mcp_server - Always search for existing knowledge before adding new information - Use specific entity type filters (`Preference`, `Procedure`, `Requirement`) - Store new information immediately using `add_memory` -- Follow discovered procedures and respect established preferences +- Follow discovered procedures and respect established preferences \ No newline at end of file diff --git a/README.md b/README.md index e6ccf811..8f022fe5 100644 --- a/README.md +++ b/README.md @@ -213,6 +213,28 @@ In addition to the Neo4j and OpenAi-compatible credentials, Graphiti also has a If you are using one of our supported models, such as Anthropic or Voyage models, the necessary environment variables must be set. +### Database Configuration + +`DEFAULT_DATABASE` specifies the database name to use for graph operations. This is particularly important for Neo4j 5+ users: + +- **Neo4j 5+**: The default database name is `neo4j` (not `default_db`) +- **Neo4j 4**: The default database name is `default_db` +- **FalkorDB**: The default graph name is `default_db` + +If you encounter the error `Graph not found: default_db` when using Neo4j 5, set: + +```bash +export DEFAULT_DATABASE=neo4j +``` + +Or add to your `.env` file: + +``` +DEFAULT_DATABASE=neo4j +``` + +### Performance Configuration + `USE_PARALLEL_RUNTIME` is an optional boolean variable that can be set to true if you wish to enable Neo4j's parallel runtime feature for several of our search queries. Note that this feature is not supported for Neo4j Community edition or for smaller AuraDB instances, diff --git a/examples/quickstart/README.md b/examples/quickstart/README.md index 988211ca..f6a28934 100644 --- a/examples/quickstart/README.md +++ b/examples/quickstart/README.md @@ -41,6 +41,9 @@ export NEO4J_PASSWORD=password # Optional FalkorDB connection parameters (defaults shown) export FALKORDB_URI=falkor://localhost:6379 + +# Database configuration (required for Neo4j 5+) +export DEFAULT_DATABASE=neo4j ``` 3. Run the example: @@ -71,6 +74,26 @@ After running this example, you can: 4. Try other predefined search recipes from `graphiti_core.search.search_config_recipes` 5. Explore the more advanced examples in the other directories +## Troubleshooting + +### "Graph not found: default_db" Error + +If you encounter the error `Neo.ClientError.Database.DatabaseNotFound: Graph not found: default_db`, this typically occurs with Neo4j 5+ where the default database name is `neo4j` instead of `default_db`. + +**Solution:** +Set the `DEFAULT_DATABASE` environment variable to `neo4j`: + +```bash +export DEFAULT_DATABASE=neo4j +``` + +Or add it to your `.env` file: +``` +DEFAULT_DATABASE=neo4j +``` + +This tells Graphiti to use the correct database name for your Neo4j version. + ## Understanding the Output ### Edge Search Results