auryn-core 0.8.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. auryn_core-0.8.1/.gitignore +56 -0
  2. auryn_core-0.8.1/LICENSE +21 -0
  3. auryn_core-0.8.1/PKG-INFO +18 -0
  4. auryn_core-0.8.1/pyproject.toml +44 -0
  5. auryn_core-0.8.1/src/auryn/__main__.py +8 -0
  6. auryn_core-0.8.1/src/auryn/assets/quickstart_sample/README.md +17 -0
  7. auryn_core-0.8.1/src/auryn/assets/quickstart_sample/app/__init__.py +7 -0
  8. auryn_core-0.8.1/src/auryn/assets/quickstart_sample/app/accounts.py +25 -0
  9. auryn_core-0.8.1/src/auryn/assets/quickstart_sample/app/api.py +30 -0
  10. auryn_core-0.8.1/src/auryn/assets/quickstart_sample/app/billing.py +31 -0
  11. auryn_core-0.8.1/src/auryn/assets/quickstart_sample/app/db.py +13 -0
  12. auryn_core-0.8.1/src/auryn/assets/skills/auryn/SKILL.md +46 -0
  13. auryn_core-0.8.1/src/auryn/cli.py +1261 -0
  14. auryn_core-0.8.1/src/auryn/core/__init__.py +0 -0
  15. auryn_core-0.8.1/src/auryn/core/agents.py +370 -0
  16. auryn_core-0.8.1/src/auryn/core/app_config.py +278 -0
  17. auryn_core-0.8.1/src/auryn/core/base_ingestor.py +93 -0
  18. auryn_core-0.8.1/src/auryn/core/cpp_headers.py +92 -0
  19. auryn_core-0.8.1/src/auryn/core/docstrings.py +134 -0
  20. auryn_core-0.8.1/src/auryn/core/embeddings/__init__.py +37 -0
  21. auryn_core-0.8.1/src/auryn/core/embeddings/documents.py +95 -0
  22. auryn_core-0.8.1/src/auryn/core/embeddings/embedder.py +153 -0
  23. auryn_core-0.8.1/src/auryn/core/embeddings/search.py +79 -0
  24. auryn_core-0.8.1/src/auryn/core/embeddings/worker.py +245 -0
  25. auryn_core-0.8.1/src/auryn/core/generated.py +103 -0
  26. auryn_core-0.8.1/src/auryn/core/git_source.py +255 -0
  27. auryn_core-0.8.1/src/auryn/core/graph_client.py +760 -0
  28. auryn_core-0.8.1/src/auryn/core/graph_model.py +38 -0
  29. auryn_core-0.8.1/src/auryn/core/graph_queries.py +1063 -0
  30. auryn_core-0.8.1/src/auryn/core/graph_sync.py +297 -0
  31. auryn_core-0.8.1/src/auryn/core/home.py +83 -0
  32. auryn_core-0.8.1/src/auryn/core/hooks.py +98 -0
  33. auryn_core-0.8.1/src/auryn/core/http_seam.py +42 -0
  34. auryn_core-0.8.1/src/auryn/core/impact.py +227 -0
  35. auryn_core-0.8.1/src/auryn/core/incremental_scoped.py +1378 -0
  36. auryn_core-0.8.1/src/auryn/core/ingest.py +733 -0
  37. auryn_core-0.8.1/src/auryn/core/install.py +71 -0
  38. auryn_core-0.8.1/src/auryn/core/instrument.py +65 -0
  39. auryn_core-0.8.1/src/auryn/core/lifecycle.py +211 -0
  40. auryn_core-0.8.1/src/auryn/core/linkage.py +347 -0
  41. auryn_core-0.8.1/src/auryn/core/local_source.py +216 -0
  42. auryn_core-0.8.1/src/auryn/core/logging_config.py +12 -0
  43. auryn_core-0.8.1/src/auryn/core/parallel.py +157 -0
  44. auryn_core-0.8.1/src/auryn/core/platform_support.py +39 -0
  45. auryn_core-0.8.1/src/auryn/core/plugins.py +149 -0
  46. auryn_core-0.8.1/src/auryn/core/portability.py +78 -0
  47. auryn_core-0.8.1/src/auryn/core/progress.py +54 -0
  48. auryn_core-0.8.1/src/auryn/core/project.py +51 -0
  49. auryn_core-0.8.1/src/auryn/core/registry.py +315 -0
  50. auryn_core-0.8.1/src/auryn/core/server_manager.py +292 -0
  51. auryn_core-0.8.1/src/auryn/core/source_filter.py +75 -0
  52. auryn_core-0.8.1/src/auryn/core/usage.py +160 -0
  53. auryn_core-0.8.1/src/auryn/core/watcher.py +243 -0
  54. auryn_core-0.8.1/src/auryn/hooks/__init__.py +10 -0
  55. auryn_core-0.8.1/src/auryn/hooks/postuse_enrich.py +792 -0
  56. auryn_core-0.8.1/src/auryn/mcp/__init__.py +2 -0
  57. auryn_core-0.8.1/src/auryn/mcp/server.py +508 -0
  58. auryn_core-0.8.1/src/auryn/viewer/__init__.py +0 -0
  59. auryn_core-0.8.1/src/auryn/viewer/app.py +273 -0
  60. auryn_core-0.8.1/src/auryn/viewer/community_names.py +64 -0
  61. auryn_core-0.8.1/src/auryn/viewer/static/css/app.css +761 -0
  62. auryn_core-0.8.1/src/auryn/viewer/static/index.html +225 -0
  63. auryn_core-0.8.1/src/auryn/viewer/static/js/api.js +71 -0
  64. auryn_core-0.8.1/src/auryn/viewer/static/js/app.js +829 -0
  65. auryn_core-0.8.1/src/auryn/viewer/static/js/palette.js +98 -0
  66. auryn_core-0.8.1/src/auryn/viewer/static/js/panels.js +419 -0
  67. auryn_core-0.8.1/src/auryn/viewer/static/js/render.js +947 -0
  68. auryn_core-0.8.1/src/auryn/viewer/static/js/vendor/graphology-library.min.js +2 -0
  69. auryn_core-0.8.1/src/auryn/viewer/static/js/vendor/graphology.umd.min.js +2 -0
  70. auryn_core-0.8.1/src/auryn/viewer/static/js/vendor/sigma.min.js +1369 -0
@@ -0,0 +1,56 @@
1
+ # Python-generated files
2
+ __pycache__/
3
+ *.py[oc]
4
+ build/
5
+ dist/
6
+ wheels/
7
+ *.egg-info
8
+
9
+ # Virtual environments
10
+ .venv
11
+
12
+ # Test/coverage artifacts
13
+ .coverage
14
+ .pytest_cache/
15
+ *.db
16
+
17
+ # Embedded-graph working dir written by `auryn quickstart` (e.g. quickstart/.auryn/)
18
+ .auryn/
19
+
20
+ # .NET build output (roslyn-extractor tool + C# test fixtures)
21
+ bin/
22
+ obj/
23
+
24
+ # Demo sample repos are generated by their setup.py / run_demo.py
25
+ demo/csharp-git/sample-repo/
26
+
27
+
28
+ # Stray FalkorDB/Redis snapshot (regenerated at runtime; never upload)
29
+ dump.rdb
30
+ *.rdb
31
+
32
+ # Deploy bundles (build artifacts)
33
+ auryn-plsql-deploy.zip
34
+ auryn-deploy.zip
35
+
36
+ # Agent-benchmark run outputs (per-run JSON logs, captured claude-config, transcripts)
37
+ benchmarks/agent/results/
38
+ benchmarks/agent/results-swe/
39
+ benchmarks/agent/results-corpus/
40
+ benchmarks/agent/results-abcd-easy/
41
+ benchmarks/agent/results-abcd-hard/
42
+ benchmarks/hook/results/
43
+ benchmarks/results/
44
+
45
+ # macOS Finder metadata
46
+ .DS_Store
47
+
48
+ # Local operator docs (client/prospect restore & VM setup) — never publish
49
+ RESTORE-*.md
50
+ INSTALL-ON-*.md
51
+
52
+ # Private, non-public hooks / work kept out of the open-source release
53
+ private/
54
+
55
+ # WIP demo not part of the public launch (kept local)
56
+ demo/auryn-tour/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 FalkorDB
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,18 @@
1
+ Metadata-Version: 2.5
2
+ Name: auryn-core
3
+ Version: 0.8.1
4
+ Summary: Core of Auryn: registry/plugin discovery, git+local sources, the FalkorDB graph layer, the MCP server, the viewer, and the `auryn` CLI. Language support ships as separate `auryn-<lang>` plugins.
5
+ Author-email: Roi Lipman <roi.lipman@falkordb.com>
6
+ License: MIT
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.12
9
+ Requires-Dist: click>=8.1
10
+ Requires-Dist: falkordb>=1.5.0
11
+ Requires-Dist: flask>=3.1.3
12
+ Requires-Dist: gitpython>=3.1.57
13
+ Requires-Dist: mcp<2.1,>=1.2
14
+ Requires-Dist: tomli-w>=1.0
15
+ Provides-Extra: embedded
16
+ Requires-Dist: falkordblite>=0.10; extra == 'embedded'
17
+ Provides-Extra: llm
18
+ Requires-Dist: anthropic>=0.40; extra == 'llm'
@@ -0,0 +1,44 @@
1
+ [project]
2
+ name = "auryn-core"
3
+ version = "0.8.1"
4
+ description = "Core of Auryn: registry/plugin discovery, git+local sources, the FalkorDB graph layer, the MCP server, the viewer, and the `auryn` CLI. Language support ships as separate `auryn-<lang>` plugins."
5
+ authors = [{ name = "Roi Lipman", email = "roi.lipman@falkordb.com" }]
6
+ requires-python = ">=3.12"
7
+ license = { text = "MIT" }
8
+ dependencies = [
9
+ "falkordb>=1.5.0",
10
+ "click>=8.1",
11
+ "flask>=3.1.3",
12
+ "gitpython>=3.1.57",
13
+ # <2.1 deliberately: mcp 2.1 masks tool exceptions as a generic "Error executing
14
+ # tool X", dropping our helpful ValueError messages (missing-node id, "call
15
+ # locate() first"). Revisit as its own task -- see MCP error-surfacing follow-up.
16
+ "mcp>=1.2,<2.1",
17
+ "tomli-w>=1.0", # write ~/.auryn/config.toml (install manifest); reads use stdlib tomllib
18
+ ]
19
+
20
+ [project.optional-dependencies]
21
+ # Optional AI enrichment for the viewer: naming detected graph communities via
22
+ # Claude (viewer/community_names.py). Imported lazily and degraded gracefully, so
23
+ # the viewer runs fine without it -- install `auryn-core[llm]` + set
24
+ # ANTHROPIC_API_KEY to enable semantic community names.
25
+ llm = ["anthropic>=0.40"]
26
+ # Optional embedded/serverless FalkorDB: bundles Redis + the FalkorDB module in-process
27
+ # (no separate server, no Docker) via falkordblite. Imported lazily -- and auto-installed
28
+ # on demand (opt-out) -- in graph_client.connect_client only when a config requests
29
+ # embedded mode, so the normal server path never carries it. Powers `auryn quickstart`.
30
+ embedded = ["falkordblite>=0.10"]
31
+
32
+ [project.scripts]
33
+ auryn = "auryn.cli:cli"
34
+
35
+ [build-system]
36
+ requires = ["hatchling"]
37
+ build-backend = "hatchling.build"
38
+
39
+ # PEP 420 namespace package: there is no src/auryn/__init__.py, so several
40
+ # distributions (this core + each auryn-<lang>) all contribute submodules to the
41
+ # shared `auryn` namespace. hatchling maps src/auryn/** -> auryn/** and
42
+ # includes the viewer's static assets (non-.py) that live under the tree.
43
+ [tool.hatch.build.targets.wheel]
44
+ packages = ["src/auryn"]
@@ -0,0 +1,8 @@
1
+ """Enable ``python -m auryn`` -- used to spawn the detached local FalkorDB daemon
2
+ (``python -m auryn serve``) with the exact interpreter/venv of the caller, regardless of
3
+ whether the ``auryn`` console script is on PATH. See core/server_manager.py."""
4
+
5
+ from auryn.cli import cli
6
+
7
+ if __name__ == "__main__":
8
+ cli()
@@ -0,0 +1,17 @@
1
+ # quickstart sample
2
+
3
+ A tiny payments API — the codebase `auryn quickstart` graphs when you run it with
4
+ no path. It's intentionally small so the graph builds in a second or two, but
5
+ structurally realistic:
6
+
7
+ ```
8
+ app/api.py 3 FastAPI routes -> become APIEndpoint entry points
9
+ app/billing.py charge_card / refund (the domain core)
10
+ app/accounts.py Account <- PremiumAccount (EXTENDS)
11
+ app/db.py connect() / Connection.execute (billing's callees)
12
+ ```
13
+
14
+ It ships inside the `auryn` package so `auryn quickstart` works the same whether
15
+ you cloned the repo or `pip install`ed it. See the top-level
16
+ [README](../../../../../../README.md#quickstart-no-server-no-docker) for the full
17
+ walkthrough, including letting a coding agent query the same graph over MCP.
@@ -0,0 +1,7 @@
1
+ """A tiny payments API — the codebase `auryn quickstart` graphs by default.
2
+
3
+ Deliberately small (a handful of files) but structurally realistic: HTTP routes
4
+ that fan out into a billing service, an accounts model with inheritance, and a
5
+ thin database layer. Enough edges to make the viewer -- and an AI agent querying
6
+ the graph -- show something worth seeing.
7
+ """
@@ -0,0 +1,25 @@
1
+ """Accounts model. `PremiumAccount` extends `Account` -- an EXTENDS edge the graph
2
+ captures, so inheritance questions ("what subclasses Account?") resolve structurally.
3
+ """
4
+
5
+ from dataclasses import dataclass
6
+
7
+
8
+ @dataclass
9
+ class Account:
10
+ id: int
11
+ limit_cents: int = 50_000
12
+
13
+
14
+ class PremiumAccount(Account):
15
+ """Vetted customers get a higher charge limit."""
16
+
17
+ def __init__(self, id: int) -> None:
18
+ super().__init__(id=id, limit_cents=500_000)
19
+
20
+
21
+ _ACCOUNTS: dict[int, Account] = {1: Account(1), 2: PremiumAccount(2)}
22
+
23
+
24
+ def get_account(account_id: int) -> Account:
25
+ return _ACCOUNTS[account_id]
@@ -0,0 +1,30 @@
1
+ """HTTP layer: three FastAPI routes that delegate into the billing/accounts services.
2
+
3
+ The route decorators become `APIEndpoint` nodes in the graph (via the python-routes
4
+ enrichment), so each handler is a first-class entry point you can `trace_entrypoint`
5
+ end to end.
6
+ """
7
+
8
+ from fastapi import FastAPI
9
+
10
+ from app.accounts import get_account
11
+ from app.billing import charge_card, refund
12
+
13
+ app = FastAPI()
14
+
15
+
16
+ @app.post("/charges")
17
+ def create_charge(account_id: int, amount_cents: int):
18
+ """Charge a card. Entry point whose call-closure reaches charge_card -> db."""
19
+ return {"result": charge_card(account_id, amount_cents)}
20
+
21
+
22
+ @app.post("/refunds")
23
+ def create_refund(charge_id: int):
24
+ return {"result": refund(charge_id)}
25
+
26
+
27
+ @app.get("/accounts/{account_id}")
28
+ def read_account(account_id: int):
29
+ account = get_account(account_id)
30
+ return {"id": account.id, "limit_cents": account.limit_cents}
@@ -0,0 +1,31 @@
1
+ """Billing service: the domain core. `charge_card` is the function the quickstart
2
+ agent example asks about -- it has both callers (the /charges endpoint) and callees
3
+ (accounts + the db layer), so it makes a good who-calls / blast-radius example.
4
+ """
5
+
6
+ from app.accounts import Account, get_account
7
+ from app.db import connect
8
+
9
+
10
+ def charge_card(account_id: int, amount_cents: int) -> str:
11
+ """Authorize and record a charge against an account."""
12
+ account = get_account(account_id)
13
+ _guard_limit(account, amount_cents)
14
+ conn = connect()
15
+ conn.execute(
16
+ "INSERT INTO charges (account_id, amount_cents) VALUES (?, ?)",
17
+ (account.id, amount_cents),
18
+ )
19
+ return f"charged {amount_cents} to account {account.id}"
20
+
21
+
22
+ def refund(charge_id: int) -> str:
23
+ """Reverse a prior charge."""
24
+ conn = connect()
25
+ conn.execute("UPDATE charges SET refunded = 1 WHERE id = ?", (charge_id,))
26
+ return f"refunded charge {charge_id}"
27
+
28
+
29
+ def _guard_limit(account: Account, amount_cents: int) -> None:
30
+ if amount_cents > account.limit_cents:
31
+ raise ValueError(f"amount {amount_cents} exceeds limit {account.limit_cents}")
@@ -0,0 +1,13 @@
1
+ """Thin database layer. A real driver would open a socket here; for the quickstart
2
+ it's a stub -- the point is the CALLS edges from billing into `Connection.execute`.
3
+ """
4
+
5
+
6
+ class Connection:
7
+ def execute(self, sql: str, params: tuple = ()) -> None:
8
+ """Run a statement. Stubbed -- a real driver would talk to the database."""
9
+ _ = (sql, params)
10
+
11
+
12
+ def connect() -> Connection:
13
+ return Connection()
@@ -0,0 +1,46 @@
1
+ ---
2
+ name: auryn
3
+ description: "Use for any structural question about a codebase — where a function/class/module is defined, who calls X, what X calls, the call path between two symbols, the blast radius of a change, or what an endpoint/handler does end to end. Prefer this over grepping and reading whole files: it queries a persistent code graph via the `auryn` MCP server and returns the precise answer (with node ids) in a single call, without pulling files into context."
4
+ ---
5
+
6
+ # Auryn
7
+
8
+ The working repository can be indexed into a queryable code graph (FalkorDB) exposed by the
9
+ `auryn` MCP server. **The graph is the map — use it to *find*, not to *search*.** A
10
+ single query returns the exact structural answer with ids; reading and grepping whole files
11
+ to reconstruct the same fact is slower, costs far more tokens, and is easy to get wrong.
12
+
13
+ ## When to reach for it
14
+
15
+ Any question about structure or relationships: "where is X", "who calls X / what depends
16
+ on it", "what does X call / depend on", "does X reach Y, and how", "what breaks if I change
17
+ X", "what does this endpoint/handler do end to end", "list the public API / entry points".
18
+
19
+ ## Workflow
20
+
21
+ 1. **`auryn_status`** — is the graph built for this repo? If it reports no data, run
22
+ **`index_repository(path=".")`** once (a one-time cost; every query after is cheap). The
23
+ local backend starts on demand, so this just works — no server to launch.
24
+ 2. **`locate(name=...)`** — turn a symbol name into its `id`; every other tool takes that
25
+ `id`, never a display name.
26
+ 3. Answer with the smallest tool that fits:
27
+ - **`who_calls(id)`** — who calls this (inward); **`callees(id)`** — what this calls
28
+ (outward). `max_depth` for transitive.
29
+ - **`find_path(from_id, to_id)`** — the shortest path between two symbols (any edge
30
+ type; pass `edge_types=["CALLS"]` for a pure call chain).
31
+ - **`impact_of(id, direction=...)`** — change blast radius across "uses" edges.
32
+ - **`trace_entrypoint(id)`** — the full call-closure of an entry point; pass a
33
+ handler, a procedure/function, or an `APIEndpoint` (endpoints resolve to their handler
34
+ first, so "what does this endpoint do end to end" works).
35
+ - **`get_context(id)`** — one node + its 1-hop neighbours + `source` text.
36
+ 4. **`get_schema`** (labels/edge-types) + **`run_cypher`** (arbitrary READ-ONLY Cypher) —
37
+ the escape hatch for anything the curated tools don't cover.
38
+
39
+ ## Rules
40
+
41
+ - Prefer a graph query over reading files; one query beats grepping several files.
42
+ - Cite the node `id` / file path the graph returns as your evidence.
43
+ - The graph is honest about confidence: type properties carry `type_source`
44
+ (annotated | inferred | unresolved) and call/inheritance edges carry `resolution`
45
+ (resolved | inferred | unresolved). Trust `resolved`/`annotated` over `inferred`, and say
46
+ so when it matters. Check `truncated` on traversal results before calling them complete.