auryn-core 0.1.0__py3-none-any.whl

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 (71) hide show
  1. auryn/__main__.py +8 -0
  2. auryn/assets/quickstart_sample/README.md +17 -0
  3. auryn/assets/quickstart_sample/app/__init__.py +7 -0
  4. auryn/assets/quickstart_sample/app/accounts.py +25 -0
  5. auryn/assets/quickstart_sample/app/api.py +30 -0
  6. auryn/assets/quickstart_sample/app/billing.py +31 -0
  7. auryn/assets/quickstart_sample/app/db.py +13 -0
  8. auryn/assets/skills/auryn/SKILL.md +46 -0
  9. auryn/cli.py +1261 -0
  10. auryn/core/__init__.py +0 -0
  11. auryn/core/agents.py +370 -0
  12. auryn/core/app_config.py +278 -0
  13. auryn/core/base_ingestor.py +93 -0
  14. auryn/core/cpp_headers.py +92 -0
  15. auryn/core/docstrings.py +134 -0
  16. auryn/core/embeddings/__init__.py +37 -0
  17. auryn/core/embeddings/documents.py +95 -0
  18. auryn/core/embeddings/embedder.py +153 -0
  19. auryn/core/embeddings/search.py +79 -0
  20. auryn/core/embeddings/worker.py +245 -0
  21. auryn/core/generated.py +103 -0
  22. auryn/core/git_source.py +255 -0
  23. auryn/core/graph_client.py +760 -0
  24. auryn/core/graph_model.py +38 -0
  25. auryn/core/graph_queries.py +1063 -0
  26. auryn/core/graph_sync.py +297 -0
  27. auryn/core/home.py +83 -0
  28. auryn/core/hooks.py +98 -0
  29. auryn/core/http_seam.py +42 -0
  30. auryn/core/impact.py +227 -0
  31. auryn/core/incremental_scoped.py +1378 -0
  32. auryn/core/ingest.py +733 -0
  33. auryn/core/install.py +71 -0
  34. auryn/core/instrument.py +65 -0
  35. auryn/core/lifecycle.py +211 -0
  36. auryn/core/linkage.py +347 -0
  37. auryn/core/local_source.py +216 -0
  38. auryn/core/logging_config.py +12 -0
  39. auryn/core/parallel.py +157 -0
  40. auryn/core/platform_support.py +39 -0
  41. auryn/core/plugins.py +149 -0
  42. auryn/core/portability.py +78 -0
  43. auryn/core/progress.py +54 -0
  44. auryn/core/project.py +51 -0
  45. auryn/core/registry.py +315 -0
  46. auryn/core/server_manager.py +292 -0
  47. auryn/core/source_filter.py +75 -0
  48. auryn/core/usage.py +160 -0
  49. auryn/core/watcher.py +243 -0
  50. auryn/hooks/__init__.py +10 -0
  51. auryn/hooks/postuse_enrich.py +792 -0
  52. auryn/mcp/__init__.py +2 -0
  53. auryn/mcp/server.py +508 -0
  54. auryn/viewer/__init__.py +0 -0
  55. auryn/viewer/app.py +273 -0
  56. auryn/viewer/community_names.py +64 -0
  57. auryn/viewer/static/css/app.css +761 -0
  58. auryn/viewer/static/index.html +225 -0
  59. auryn/viewer/static/js/api.js +71 -0
  60. auryn/viewer/static/js/app.js +829 -0
  61. auryn/viewer/static/js/palette.js +98 -0
  62. auryn/viewer/static/js/panels.js +419 -0
  63. auryn/viewer/static/js/render.js +947 -0
  64. auryn/viewer/static/js/vendor/graphology-library.min.js +2 -0
  65. auryn/viewer/static/js/vendor/graphology.umd.min.js +2 -0
  66. auryn/viewer/static/js/vendor/sigma.min.js +1369 -0
  67. auryn_core-0.1.0.dist-info/METADATA +18 -0
  68. auryn_core-0.1.0.dist-info/RECORD +71 -0
  69. auryn_core-0.1.0.dist-info/WHEEL +4 -0
  70. auryn_core-0.1.0.dist-info/entry_points.txt +2 -0
  71. auryn_core-0.1.0.dist-info/licenses/LICENSE +557 -0
auryn/__main__.py ADDED
@@ -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.