Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
54 commits
Select commit Hold shift + click to select a range
3cf1875
feat: add a wrapped stats endpoint
devodii Nov 15, 2026
b6bdc16
feat: add the wrapped data hook
devodii Nov 15, 2026
a3e0b69
feat: add a fixed size stage for the wrapped poster
devodii Nov 15, 2026
9353bed
feat: add ai coding agents to the integration catalog
devodii Nov 15, 2026
90b568f
feat: record the ai agents each repo uses
devodii Nov 15, 2026
543fb9a
feat: catalog stellar raven, stellar skills and the agents seen in th…
devodii Nov 15, 2026
ec48128
feat: expose ai agents on projects and an agents endpoint
devodii Nov 15, 2026
75fa64f
refactor: keep only the new numbers in the wrapped endpoint
devodii Nov 15, 2026
ff98afb
feat: add design tokens for the wrapped poster
devodii Nov 15, 2026
3e97c0b
feat: add ai agents to the web types and hooks
devodii Nov 15, 2026
9e4be13
feat: add lens helpers for the wrapped poster
devodii Nov 15, 2026
911af39
refactor: move the still context into its own file
devodii Nov 15, 2026
df0da88
feat: add the wrapped tile and animated figure
devodii Nov 15, 2026
82d2750
feat: add a hoverable project waffle
devodii Nov 15, 2026
68da38e
feat: add the lens list and segmented bar
devodii Nov 15, 2026
a4918f6
feat: add the wrapped charts
devodii Nov 15, 2026
94c570d
feat: add builder avatars
devodii Nov 15, 2026
4f57b20
feat: add the wrapped page
devodii Nov 15, 2026
011f303
feat: export the ai agents each project uses
devodii Nov 15, 2026
2f8a0b0
feat: add ai agents and the new stellar tools to the project files
devodii Nov 15, 2026
17b1ace
docs: describe the tools and agents fields
devodii Nov 15, 2026
1121ec8
fix: hide a wrapped list tile that has nothing to show
devodii Nov 15, 2026
adf6f7f
feat: filter the explorer by ai coding agent
devodii Nov 15, 2026
c7ca149
feat: link the wrapped categories to the explorer
devodii Nov 15, 2026
0e344cc
fix: teach the class merger the poster font sizes
devodii Nov 15, 2026
34d023a
fix: size animated numbers by their final value
devodii Nov 15, 2026
986e497
fix: show the chart markers after the line is drawn
devodii Nov 15, 2026
d1b0552
fix: center the wrapped stage on any screen size
devodii Nov 15, 2026
c13cdbf
feat: add a media query hook
devodii Nov 15, 2026
017a27a
fix: space the timeline ticks by screen size
devodii Nov 15, 2026
08ffc98
feat: add a scrolling layout of the wrapped page for small screens
devodii Nov 15, 2026
4aaa64d
feat: add a contributor profile endpoint
devodii Nov 15, 2026
963aa39
refactor: move the filter options out of the panel
devodii Nov 15, 2026
66b8922
feat: link the wrapped page from the site header
devodii Nov 15, 2026
ea53fea
feat: title the filtered projects page and add a back button
devodii Nov 15, 2026
e1dfb6f
feat: show a contributor's commits on a project card
devodii Nov 15, 2026
5c3e8e6
feat: add the contributor profile page
devodii Nov 15, 2026
64592d4
feat: link builder avatars to their contributor profile
devodii Nov 15, 2026
056e55b
feat: filter projects by agent, language, country, activity and award
devodii Nov 15, 2026
c77829e
feat: give the chat the filtered view and every explorer filter
devodii Nov 15, 2026
4baa946
feat: give each filter a list of suggested questions
devodii Nov 15, 2026
0416df7
feat: suggest questions on the filtered projects page
devodii Nov 15, 2026
7cf338a
feat: send the active filters to the chat and suggest questions for them
devodii Nov 15, 2026
727c780
refactor: use one event name constant
devodii Nov 15, 2026
7548073
feat: give each filter a title clause
devodii Nov 15, 2026
f3f3968
feat: name the event and the filters in the filtered page title
devodii Nov 15, 2026
9c8583c
feat: name the event on the builder page
devodii Nov 15, 2026
0711a03
feat: show the contributors first and open on the project page
devodii Nov 15, 2026
68e1372
feat: add a command that checks the database against the committed da…
devodii Nov 15, 2026
038212c
docs: describe the check command
devodii Nov 15, 2026
5563a97
feat: list the projects of each wrapped builder
devodii Nov 15, 2026
2e32ab7
refactor: share the back button
devodii Nov 15, 2026
fe2c8a3
feat: add a page that lists the builders on two or more teams
devodii Nov 15, 2026
d9cff09
feat: link the builders overflow count to the full list
devodii Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 129 additions & 2 deletions apps/api/src/hackproof/chat/briefs.py
Original file line number Diff line number Diff line change
@@ -1,21 +1,88 @@
import json
from collections import Counter
from typing import Any, Literal

from pydantic import BaseModel
from pydantic import BaseModel, Field
from pydantic_core import to_jsonable_python

from hackproof import queries
from hackproof.chat.prompts import prompt
from hackproof.hackathon import Place
from hackproof.schemas import Tier

HEAVY_FIELDS = {"dependencies", "owner_avatar"}
SAMPLE = 8
STRICT: list[Tier] = ["verified", "likely"]

PageKind = Literal["home", "project", "builder"]
PageKind = Literal["home", "project", "builder", "filter"]
Track = Literal["genesis", "scale"]


class Page(BaseModel):
kind: PageKind
id: str | None = None
filters: dict[str, list[str]] | None = None


class ProjectFilters(BaseModel):
tiers: list[Tier] | None = Field(
default=None, description="Evidence tiers to include; null means verified and likely"
)
track: Track | None = Field(
default=None,
description="genesis (repo created inside the window) or scale (older repo); null for both",
)
integrations: list[str] | None = Field(
default=None,
description="Partner slugs from get_integrations; keeps projects using any of them",
)
tools: list[str] | None = Field(
default=None,
description="Stellar tooling slugs from get_tools; keeps projects using any of them",
)
agents: list[str] | None = Field(
default=None,
description="AI coding agent slugs from get_agents; keeps projects showing any of them",
)
languages: list[str] | None = Field(
default=None, description="Primary repo languages, such as TypeScript or Rust"
)
countries: list[str] | None = Field(
default=None, description="ISO 3166-1 alpha-2 codes of the repo owner's country"
)
activity: list[Literal["contracts", "failed"]] | None = Field(
default=None,
description="contracts keeps projects that deployed contracts; failed keeps projects "
"with failed transactions",
)
awards: list[Place] | None = Field(
default=None, description="first or runner-up keeps projects that won that award"
)

def list_args(self) -> dict[str, Any]:
return {
"tiers": self.tiers or STRICT,
"track": self.track,
"integrations": self.integrations,
"tools": self.tools,
"agents": self.agents,
"languages": self.languages,
"countries": self.countries,
"activity": self.activity,
"awards": self.awards,
}


PAGE_FILTERS = {
"tier": "tiers",
"partner": "integrations",
"tool": "tools",
"agent": "agents",
"language": "languages",
"country": "countries",
"activity": "activity",
"award": "awards",
}


def slim(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
Expand Down Expand Up @@ -78,11 +145,71 @@ async def builder_brief(address: str) -> dict[str, Any] | None:
)


def _top(counter: Counter[str], size: int) -> list[dict[str, Any]]:
return [{"name": name, "projects": count} for name, count in counter.most_common(size)]


async def summarize_view(filters: ProjectFilters) -> dict[str, Any]:
items, total = await queries.list_page("projects", **filters.list_args(), limit=10_000)
topics: Counter[str] = Counter()
stack: Counter[str] = Counter()
partners: Counter[str] = Counter()
tooling: Counter[str] = Counter()
agents: Counter[str] = Counter()
for item in items:
topics.update(topic.lower() for topic in item["topics"] or [])
stack.update(list((item["dependencies"] or {}).get("packages", {})))
partners.update(item["integrations"])
tooling.update(item["tools"])
agents.update(item["agents"])
return {
"total": total,
"by_tier": dict(Counter(item["tier"] for item in items)),
"by_track": dict(Counter(item["track"] for item in items)),
"contracts": sum(item["contracts"] for item in items),
"wasm_uploads": sum(item["wasm_uploads"] for item in items),
"languages": _top(Counter(item["language"] for item in items if item["language"]), 10),
"topics": _top(topics, 20),
"stellar_packages": _top(stack, 15),
"integrations": _top(partners, 15),
"stellar_tooling": _top(tooling, 10),
"ai_agents": _top(agents, 10),
"countries": _top(Counter(item["country"] for item in items if item["country"]), 10),
"descriptions": [
{"project_id": item["project_id"], "description": item["description"][:140]}
for item in items
if item["description"]
][:25],
}


def view_filters(selected: dict[str, list[str]]) -> ProjectFilters:
known = {
PAGE_FILTERS[key]: values[:20] for key, values in selected.items() if key in PAGE_FILTERS
}
tracks = selected.get("track", [])
return ProjectFilters.model_validate(
{**known, "track": tracks[0] if len(tracks) == 1 else None}
)


async def filter_brief(selected: dict[str, list[str]]) -> str:
filters = view_filters(selected)
summary = await summarize_view(filters)
return prompt(
"page-filter",
filters=json.dumps(selected),
data=json.dumps(to_jsonable_python(summary), default=str),
)


async def describe_page(page: Page | None) -> str:
if page is None:
return ""
if page.kind == "home":
return prompt("page-home")
if page.kind == "filter":
return await filter_brief(page.filters or {})
if not page.id:
return ""

Expand Down
11 changes: 11 additions & 0 deletions apps/api/src/hackproof/chat/system-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,18 @@ Track is inferred, not declared. A project is genesis when its repo was created

Integrations: each project has integrations, the slugs of Stellar ecosystem partners from the SCF integration list that its code uses. A partner is detected from a package in a dependency manifest in any language, or from the partner's API host in source or config. These are evidence of use, not of a working integration.

Stellar tooling: each project has tools, the slugs of Stellar developer tools it uses: Scaffold Stellar, Stellar Registry, Stellar Raven (Stellar's own assistant, detected from its MCP endpoint in agent config) and Stellar Skills. Detection reads manifests and hosts in code and config.

AI agents: each project has agents, the slugs of AI coding agents it shows traces of. Detection reads agent config files in the repo, such as CLAUDE.md, .cursor or .codex, and commit authors such as the claude or cursoragent accounts. AGENTS.md is a convention several tools share, so it is not one tool. This is a lower bound: a team that used an agent without leaving a trace is not counted, so never say how many teams did not use AI.

Other fields: contracts, wasm_uploads, failed_txs and classic_ops count on chain activity inside the window. builders is the number of deploy accounts. window_commits and total_commits come from GitHub. stack lists the Stellar packages the repo declares. topics are the GitHub topics the team chose. country comes from the owner's public GitHub location and is often missing.

### How to work

- Use the tools for every fact and number. Never guess, and never estimate a count by counting rows yourself. Use the total returned by a tool.
- For questions about what projects are about, how many there are, or any breakdown by track, tier, language, topic or stack, call summarize_projects first. It aggregates over every matching project. Then call query_projects to show examples.
- For questions about which projects use a partner such as Trustless Work, Privy, Soroswap or Stellar Wallets Kit, call get_integrations for the slugs and counts, then query_projects with integrations set. Say that detection reads dependency manifests and API hosts in code, so a project that only mentions a partner in prose is not counted.
- For questions about Stellar tools, call get_tools for the slugs and counts. For questions about AI agents, call get_agents. Then pass the slugs as tools or agents to query_projects or summarize_projects. Both tools also filter by languages, countries, activity and awards.
- For one project call get_project. For one deploy account call get_builder. For counts and the headline numbers call get_stats. For activity over time call get_timeline. For geography call get_countries.
- Searching with q matches project ids and descriptions only. It is not a way to filter by track or tier. Use the track and tiers arguments.
- Several independent tool calls can go in one turn. Do that instead of one at a time.
Expand Down Expand Up @@ -75,3 +80,9 @@ The user is on the page for {subject}. Read "{pronoun}", "it" and "here" as this
## page-empty

The user is on the page for {subject}, which has no data inside the hack window.

## page-filter

The user is on the home page, looking at the explorer filtered by {filters}. The keys are the site's filter names: tier, track, award, partner (the integrations argument), tool, agent, language, country and activity. Read "these projects", "this view", "they" and "them" as the projects matching exactly those filters, and keep every tool call inside them by passing the same filters. A summary of the matching set is already loaded below, so do not fetch it again for basic questions.

{data}
97 changes: 25 additions & 72 deletions apps/api/src/hackproof/chat/tools.py
Original file line number Diff line number Diff line change
@@ -1,15 +1,11 @@
from collections import Counter
from typing import Annotated, Any, Literal
from typing import Annotated, Any

from pydantic import BaseModel, Field
from pydantic_core import to_jsonable_python

from hackproof import queries
from hackproof.chat.briefs import builder_brief, project_brief, slim
from hackproof.schemas import Tier
from hackproof.chat.briefs import ProjectFilters, builder_brief, project_brief, slim, summarize_view

Track = Literal["genesis", "scale"]
STRICT = ["verified", "likely"]
WEB_SEARCH = {"type": "web_search_20250305", "name": "web_search", "max_uses": 3}

Limit = Annotated[int, Field(ge=1, le=25, description="Rows to return")]
Expand All @@ -19,22 +15,11 @@
]


class QueryProjects(BaseModel):
class QueryProjects(ProjectFilters):
"""Find HackMeridian projects. Ordered by evidence strength, then on-chain activity. Each
project has an award field: first, runner-up, or null."""

q: Search = None
tiers: list[Tier] | None = Field(
default=None, description="Evidence tiers to include; null means verified and likely"
)
track: Track | None = Field(
default=None,
description="genesis (repo created inside the window) or scale (older repo); null for both",
)
integrations: list[str] | None = Field(
default=None,
description="Partner slugs from get_integrations; keeps projects using any of them",
)
winners: bool = Field(
default=False,
description="True keeps only the HackMeridian award winners: first place and runner-ups",
Expand Down Expand Up @@ -71,19 +56,10 @@ class QueryFailed(BaseModel):
offset: Offset = 0


class SummarizeProjects(BaseModel):
class SummarizeProjects(ProjectFilters):
"""Aggregate every matching project: counts by tier and track, on chain totals, top
languages, topics, Stellar packages and countries, plus a sample of descriptions. Use this
for any breakdown or "what are they building" question."""

tiers: list[Tier] | None = Field(
default=None, description="Evidence tiers to include; null means verified and likely"
)
track: Track | None = Field(default=None, description="genesis, scale, or null for both")
integrations: list[str] | None = Field(
default=None,
description="Partner slugs from get_integrations; keeps projects using any of them",
)
languages, topics, Stellar packages, integrations, tooling, AI agents and countries, plus a
sample of descriptions. Use this for any breakdown or "what are they building" question."""


class GetProject(BaseModel):
Expand All @@ -104,6 +80,17 @@ class GetIntegrations(BaseModel):
hosts in code, not from READMEs."""


class GetTools(BaseModel):
"""List the Stellar developer tools we detect (such as Scaffold Stellar, Stellar Registry,
Stellar Raven and Stellar Skills) with how many verified and likely projects use each."""


class GetAgents(BaseModel):
"""List the AI coding agents we detect (slug, name) with how many verified and likely projects
show each. Detection reads agent config files such as CLAUDE.md or .cursor and commit authors,
so it is a lower bound: a tool that leaves no trace is not counted."""


class GetStats(BaseModel):
"""Headline counts: projects by tier, contracts, builders, contributors, countries."""

Expand All @@ -125,6 +112,8 @@ class GetCountries(BaseModel):
"get_project": GetProject,
"get_builder": GetBuilder,
"get_integrations": GetIntegrations,
"get_tools": GetTools,
"get_agents": GetAgents,
"get_stats": GetStats,
"get_timeline": GetTimeline,
"get_countries": GetCountries,
Expand All @@ -140,54 +129,14 @@ class GetCountries(BaseModel):
]


def _top(counter: Counter[str], size: int) -> list[dict[str, Any]]:
return [{"name": name, "projects": count} for name, count in counter.most_common(size)]


async def summarize(args: SummarizeProjects) -> dict[str, Any]:
items, total = await queries.list_page(
"projects",
tiers=args.tiers or STRICT,
track=args.track,
integrations=args.integrations,
limit=10_000,
)
topics: Counter[str] = Counter()
stack: Counter[str] = Counter()
partners: Counter[str] = Counter()
for item in items:
topics.update(topic.lower() for topic in item["topics"] or [])
stack.update(list((item["dependencies"] or {}).get("packages", {})))
partners.update(item["integrations"])
return {
"total": total,
"by_tier": dict(Counter(item["tier"] for item in items)),
"by_track": dict(Counter(item["track"] for item in items)),
"contracts": sum(item["contracts"] for item in items),
"wasm_uploads": sum(item["wasm_uploads"] for item in items),
"languages": _top(Counter(item["language"] for item in items if item["language"]), 10),
"topics": _top(topics, 20),
"stellar_packages": _top(stack, 15),
"integrations": _top(partners, 15),
"countries": _top(Counter(item["country"] for item in items if item["country"]), 10),
"descriptions": [
{"project_id": item["project_id"], "description": item["description"][:140]}
for item in items
if item["description"]
][:25],
}


async def run_tool(name: str, raw: dict[str, Any]) -> Any:
args = TOOLS[name].model_validate(raw)
match args:
case QueryProjects():
items, total = await queries.list_page(
"projects",
**args.list_args(),
q=args.q,
tiers=args.tiers or STRICT,
track=args.track,
integrations=args.integrations,
winners=args.winners,
limit=args.limit,
offset=args.offset,
Expand All @@ -210,13 +159,17 @@ async def run_tool(name: str, raw: dict[str, Any]) -> Any:
"failed", q=args.q, account=args.account, limit=args.limit, offset=args.offset
)
case SummarizeProjects():
return to_jsonable_python(await summarize(args))
return to_jsonable_python(await summarize_view(args))
case GetProject():
return await project_brief(args.project_id) or {"error": "project not found"}
case GetBuilder():
return await builder_brief(args.address) or {"error": "no activity in the hack window"}
case GetIntegrations():
return to_jsonable_python(await queries.fetch_integrations())
case GetTools():
return to_jsonable_python(await queries.fetch_tools())
case GetAgents():
return to_jsonable_python(await queries.fetch_agents())
case GetStats():
return to_jsonable_python(await queries.fetch_stats())
case GetTimeline():
Expand Down
7 changes: 6 additions & 1 deletion apps/api/src/hackproof/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
import asyncio
import logging

from hackproof.export.jobs import run_export
from hackproof.export.jobs import run_check, run_export
from hackproof.github.jobs import run_discover, run_scan
from hackproof.indexer.sync import run_sync
from hackproof.linking.reconcile import run_reconcile
Expand All @@ -23,6 +23,9 @@ def main() -> None:
)
commands.add_parser("reconcile", help="link chain activity to repos and build projects")
commands.add_parser("export", help="write one yaml file per project into data and its schema")
commands.add_parser(
"check", help="check, read-only, that the database matches the committed data files"
)
args = parser.parse_args()

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")
Expand All @@ -38,3 +41,5 @@ def main() -> None:
asyncio.run(run_reconcile())
case "export":
asyncio.run(run_export())
case "check":
raise SystemExit(asyncio.run(run_check()))
Loading
Loading