{
  "name": "Git.Top Agent API Examples",
  "positioning": "The Knowledge Graph of Open Source",
  "summary": "Copyable REST, MCP, and GRP examples for agents that need project knowledge, recommendations, graph context, alternatives, comparisons, Atlas journeys, and production trust checks.",
  "decision_examples": [
    {
      "id": "choose-cloudflare-agent-framework",
      "title": "Choose an agent framework for Cloudflare Workers",
      "user_request": "Choose an open-source agent framework that can run on Cloudflare Workers and explain the evidence.",
      "shortest_rest_path": [
        "GET /api/trust",
        "POST /api/workflow",
        "GET /api/project/cloudflare/agents"
      ],
      "shortest_mcp_path": [
        "get_agent_workflow",
        "get_project"
      ],
      "expected_fields": [
        "shortlist",
        "decision_summary",
        "classification",
        "caveats",
        "metadata.source"
      ],
      "example_final_answer": "For this Cloudflare-specific target, cloudflare/agents is the current shortlist match with high recommendation confidence and matched deployment, category, and Cloudflare-readiness constraints. The project record says it is designed for Cloudflare-native, stateful agents. Caveat: classification and several quality signals are low-confidence or partial, so verify the deployment guide and run a Workers proof of concept before adoption.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "next_action": "Inspect the repository deployment instructions and compare a proof of concept against any non-Workers runtime requirement."
    },
    {
      "id": "compare-local-coding-agents",
      "title": "Compare two coding agents for local use",
      "user_request": "Compare Codex and OpenCode for a local coding-agent workflow.",
      "shortest_rest_path": [
        "GET /api/trust",
        "POST /api/compare"
      ],
      "shortest_mcp_path": [
        "compare_projects"
      ],
      "expected_fields": [
        "context",
        "decision_matrix",
        "winner",
        "reasoning",
        "metadata.snapshot_id"
      ],
      "example_final_answer": "For the local-deployment context in this snapshot, openai/codex ranks ahead of anomalyco/opencode. Both match the local preference. Caveat: both carry a 24/100 maintenance signal in the current comparison. Treat Codex as the contextual leader, not a universal winner, and inspect recent releases and issue activity for both before choosing.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "next_action": "Run the same representative repository task in both clients and compare tool reliability, edit quality, and operational cost."
    },
    {
      "id": "check-unfamiliar-dependency",
      "title": "Check an unfamiliar dependency before adding it",
      "user_request": "Should I add cloudflare/agents to a Python-first agent stack?",
      "shortest_rest_path": [
        "GET /api/trust",
        "GET /api/project/cloudflare/agents"
      ],
      "shortest_mcp_path": [
        "get_project"
      ],
      "expected_fields": [
        "summary.good_for",
        "summary.not_good_for",
        "classification",
        "quality_signal_confidence",
        "caveats"
      ],
      "example_final_answer": "Do not select cloudflare/agents by default for a Python-first stack. Its strongest fit is Cloudflare-native, stateful agents on Workers, while the project summary explicitly lists Python-first stacks as a poor fit. Caveat: the current record has incomplete classification and quality evidence, so confirm language and integration requirements in the upstream repository before ruling it in or out.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "next_action": "Confirm whether the application can use a TypeScript Workers boundary; otherwise compare a Python-native framework."
    },
    {
      "id": "find-langchain-alternative",
      "title": "Find a credible LangChain alternative",
      "user_request": "Find maintained alternatives to LangChain and distinguish direct replacements from adjacent options.",
      "shortest_rest_path": [
        "GET /api/trust",
        "GET /api/alternatives/langchain",
        "POST /api/compare"
      ],
      "shortest_mcp_path": [
        "get_alternatives",
        "compare_projects"
      ],
      "expected_fields": [
        "alternative_matches",
        "fit_summary",
        "replacement_risk",
        "caveats",
        "metadata.source"
      ],
      "example_final_answer": "superagent-ai/superagent is the top direct alternative in this snapshot, with 93/100 similarity and low replacement risk. TransformerOptimus/SuperAGI is another direct-category candidate. run-llama/llama_index is adjacent rather than drop-in because its category differs. Caveat: estimated activity signals and API compatibility still need upstream verification.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "next_action": "Compare the top direct candidate with LangChain against the exact integrations, deployment model, and migration surface you use."
    },
    {
      "id": "choose-docker-vector-database",
      "title": "Choose a vector database for Docker",
      "user_request": "Recommend a vector database that can be self-hosted with Docker.",
      "shortest_rest_path": [
        "GET /api/trust",
        "POST /api/recommend",
        "POST /api/compare"
      ],
      "shortest_mcp_path": [
        "recommend_project",
        "compare_projects"
      ],
      "expected_fields": [
        "recommendations",
        "matched_constraints",
        "risk_flags",
        "confidence",
        "caveats"
      ],
      "example_final_answer": "Redis and Milvus are tied at 62/100 in this Docker-constrained snapshot, with Qdrant close behind at 61/100; all are medium-confidence exploration candidates. Do not choose from score alone. Each carries a weak maintenance warning in the indexed evidence and is unsuitable for edge-only Workers deployment without adaptation.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "next_action": "Compare operational footprint, filtering requirements, scale, backup model, and client-language support before running a workload benchmark."
    },
    {
      "id": "replace-archived-python-agent-framework",
      "title": "Replace an archived Python agent framework",
      "user_request": "Find a maintained replacement for the archived microsoft/TaskWeaver project for local Python tool execution.",
      "shortest_rest_path": [
        "GET /api/trust",
        "POST /api/recommend",
        "GET /api/project/langchain-ai/langchain",
        "POST /api/compare"
      ],
      "shortest_mcp_path": [
        "recommend_project",
        "get_project",
        "compare_projects"
      ],
      "expected_fields": [
        "recommendations",
        "matched_constraints",
        "confidence",
        "classification",
        "caveats",
        "metadata.snapshot_id",
        "external_evidence"
      ],
      "example_final_answer": "GitHub reports microsoft/TaskWeaver as archived. For a local Python agent-framework replacement, Git.Top ranks langchain-ai/langchain first at 65/100 with medium confidence, followed by pydantic/pydantic-ai at 45/100 with medium confidence. Caveat: this is not a drop-in compatibility claim; LangChain's indexed classification is low-confidence and the candidates need API, tool-execution, and migration testing against the TaskWeaver workload.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "external_evidence": [
        {
          "source": "github_api",
          "subject": "microsoft/TaskWeaver",
          "verified_at": "2026-07-31",
          "url": "https://api.github.com/repos/microsoft/TaskWeaver",
          "facts": [
            "archived=true",
            "disabled=false"
          ]
        }
      ],
      "next_action": "List the TaskWeaver APIs and execution behaviors in use, then run the same tool task in LangChain and Pydantic AI before selecting a migration target."
    },
    {
      "id": "choose-local-llm-runtime",
      "title": "Choose a local LLM runtime",
      "user_request": "Choose among Ollama, llama.cpp, and GPT4All for a local inference workflow.",
      "shortest_rest_path": [
        "GET /api/trust",
        "GET /api/search",
        "POST /api/compare",
        "GET /api/project/ollama/ollama"
      ],
      "shortest_mcp_path": [
        "search_projects",
        "compare_projects",
        "get_project"
      ],
      "expected_fields": [
        "projects",
        "decision_matrix",
        "winner",
        "classification",
        "quality_signal_confidence",
        "caveats",
        "metadata.snapshot_id"
      ],
      "example_final_answer": "For the local-deployment context in this snapshot, ollama/ollama is the contextual winner over ggml-org/llama.cpp and nomic-ai/gpt4all. All three have a 79/100 Git.Top score and a 24/100 maintenance signal; llama.cpp has the strongest indexed category confidence. Caveat: the comparison does not model hardware, quantization, model-format, or throughput requirements, so Ollama is a workflow starting point rather than a universal runtime winner.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "next_action": "Benchmark the same model and prompt set on target hardware, including memory use, startup time, throughput, model-format support, and API compatibility."
    },
    {
      "id": "choose-github-automation-mcp-server",
      "title": "Choose an MCP server for GitHub automation",
      "user_request": "Choose an MCP server for repository and pull-request automation on GitHub.",
      "shortest_rest_path": [
        "GET /api/trust",
        "GET /api/search",
        "GET /api/project/github/github-mcp-server"
      ],
      "shortest_mcp_path": [
        "search_projects",
        "get_project"
      ],
      "expected_fields": [
        "projects",
        "project_id",
        "summary",
        "classification",
        "git_top_score",
        "quality_score",
        "caveats",
        "metadata.source"
      ],
      "example_final_answer": "github/github-mcp-server is the exact-purpose candidate in this snapshot: its indexed description is an MCP server for GitHub developer tools, its MCP-server classification is high-confidence, and its Git.Top score is 79/100. Caveat: its quality score is 43/100, maintenance signal is 24/100, and the generic recommender gives this exact use case low confidence. Prefer it for a proof of concept because of purpose fit, then validate authentication scopes and every mutation tool before operational use.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "next_action": "Connect it with a least-privilege test token and verify read-only repository queries before testing issue or pull-request mutations in a disposable repository."
    },
    {
      "id": "assemble-rag-stack-with-observability",
      "title": "Assemble a RAG stack with observability",
      "user_request": "Draft a self-hosted Docker RAG stack with observability and provide citable trust evidence.",
      "shortest_rest_path": [
        "GET /api/trust",
        "POST /api/grp/query",
        "GET /api/project/run-llama/llama_index",
        "GET /api/project/SigNoz/signoz"
      ],
      "shortest_mcp_path": [
        "get_trust_gate",
        "git_top_grp_query",
        "get_project"
      ],
      "expected_fields": [
        "decision",
        "checks",
        "solution_paths",
        "recommended_stack",
        "stack_roles",
        "tradeoffs",
        "metadata.data_source",
        "caveats"
      ],
      "example_final_answer": "Use the GRP result only as an architecture draft: LlamaIndex fills the memory role, LangChain the agent-core role, Docker the runtime, and SigNoz the observability role. The leading path scores 72/100. Do not present this as production-ready: the Trust Gate is block because sync and hot-corpus freshness fail, and the bounded graph reports missing or weak protocol, tool-execution, and LLM-access coverage.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "next_action": "Pin one project per required role, verify supported integrations and licenses upstream, then build a traced ingestion-and-retrieval proof of concept before re-running the trust gate."
    },
    {
      "id": "distinguish-collection-from-project",
      "title": "Distinguish a collection from an executable project",
      "user_request": "Can I adopt run-llama/awesome-rag as my RAG runtime, or should I use LlamaIndex?",
      "shortest_rest_path": [
        "GET /api/trust",
        "GET /api/project/run-llama/awesome-rag",
        "GET /api/project/run-llama/llama_index",
        "POST /api/compare"
      ],
      "shortest_mcp_path": [
        "get_project",
        "compare_projects"
      ],
      "expected_fields": [
        "project_kind",
        "collection_metadata",
        "summary.install",
        "decision_matrix",
        "winner",
        "caveats",
        "metadata.source"
      ],
      "example_final_answer": "Do not adopt run-llama/awesome-rag as a runtime. Git.Top identifies it as a curated collection with an estimated 100 items and no direct install step. For an executable local RAG project, run-llama/llama_index wins the comparison and carries a 91/100 agent score and 88/100 quality score. Caveat: the collection remains useful for discovery, but its 80/100 Git.Top score is not runtime suitability and should not be compared as if it were an installable library.",
      "verification": {
        "scope": "local_d1",
        "verified_at": "2026-07-31",
        "snapshot_id": "d1:504:2026-06-20T00:00:00Z",
        "source": "d1"
      },
      "next_action": "Use the collection to expand the shortlist, then evaluate LlamaIndex and other executable candidates against ingestion, retrieval, storage, and deployment requirements."
    }
  ],
  "examples": [
    {
      "id": "health-gate",
      "title": "Require D1-backed data",
      "intent": "Check whether production recommendations can be treated as high-confidence.",
      "surface": "REST",
      "method": "GET",
      "endpoint": "/api/health",
      "command": "curl https://git.top/api/health",
      "inspect": [
        "db",
        "metadata.source",
        "sync_health",
        "sync_freshness"
      ],
      "trust_checks": [
        "metadata.source=d1",
        "db=available"
      ],
      "next": "Add require_d1=true to critical read APIs when fallback data should be rejected."
    },
    {
      "id": "agent-surface-map",
      "title": "Choose the right surface",
      "intent": "Map a user intent to the matching human page, REST endpoint, MCP tool, output fields, and trust fields.",
      "surface": "REST",
      "method": "GET",
      "endpoint": "/api/agent-map",
      "command": "curl https://git.top/api/agent-map",
      "inspect": [
        "surfaces[].concept",
        "surfaces[].rest",
        "surfaces[].mcp_tools",
        "surfaces[].trust_fields"
      ],
      "trust_checks": [
        "trust_policy.high_confidence_source",
        "surfaces[].trust_fields"
      ],
      "next": "Use the selected surface before calling project lookup, recommendations, graph, alternatives, compare, score, Atlas, or quality."
    },
    {
      "id": "cloudflare-agent-workflow",
      "title": "Run a constrained selection workflow",
      "intent": "Choose a Cloudflare-ready agent framework with an explainable shortlist and trust policy.",
      "surface": "REST",
      "method": "GET",
      "endpoint": "/api/workflow",
      "command": "curl \"https://git.top/api/workflow?intent=choose%20a%20Cloudflare-ready%20agent%20framework&deployment=cloudflare&category=agent_framework&cloudflare_ready=true&limit=5&require_d1=true\"",
      "inspect": [
        "recommended_sequence",
        "shortlist",
        "trend_context",
        "trust_policy",
        "metadata.source"
      ],
      "trust_checks": [
        "metadata.source=d1",
        "shortlist[].confidence",
        "trust_policy.disclose_when"
      ],
      "next": "Inspect the top project, graph context, score explanation, and compare matrix before answering."
    },
    {
      "id": "structured-recommend",
      "title": "Recommend from structured JSON",
      "intent": "Use POST when an agent has nested constraints or wants a stable request body.",
      "surface": "REST",
      "method": "POST",
      "endpoint": "/api/recommend",
      "command": "curl -X POST \"https://git.top/api/recommend?require_d1=true\" -H \"content-type: application/json\" -d '{\"use_case\":\"build browser automation agents\",\"constraints\":{\"deployment\":\"docker\",\"category\":\"browser_agent\"},\"limit\":5}'",
      "inspect": [
        "recommendations[].decision_summary",
        "recommendations[].fit_profile",
        "recommendations[].risk_flags",
        "recommendations[].ranking_signals"
      ],
      "trust_checks": [
        "metadata.source=d1",
        "recommendations[].confidence",
        "recommendations[].unmatched_constraints"
      ],
      "next": "Return the top fit, one credible alternative, caveats, and the data source."
    },
    {
      "id": "compare-shortlist",
      "title": "Compare candidates",
      "intent": "Turn a shortlist into a decision matrix instead of a star-only ranking.",
      "surface": "REST",
      "method": "GET",
      "endpoint": "/api/compare",
      "command": "curl \"https://git.top/api/compare?repos=cloudflare/agents,langchain-ai/langchain,run-llama/llama_index&deployment=cloudflare&require_d1=true\"",
      "inspect": [
        "summary",
        "decision_matrix",
        "winner",
        "reasoning",
        "next_actions"
      ],
      "trust_checks": [
        "metadata.source=d1",
        "context.deployment",
        "decision_matrix[].tradeoffs"
      ],
      "next": "Move into graph or score endpoints when the decision matrix needs evidence."
    },
    {
      "id": "atlas-journeys",
      "title": "Move from ecosystem map to comparison path",
      "intent": "Use Atlas journeys to turn an ecosystem into ordered exploration steps and concrete compare URLs.",
      "surface": "REST",
      "method": "GET",
      "endpoint": "/api/journeys",
      "command": "curl https://git.top/api/journeys?limit=8&require_d1=true",
      "inspect": [
        "journeys[].steps",
        "comparison_paths",
        "comparison_paths[].api_href",
        "stats.comparison_path_count"
      ],
      "trust_checks": [
        "metadata.source=d1",
        "comparison_paths[].context",
        "journeys[].ecosystem_id"
      ],
      "next": "Run the selected comparison_paths[].api_href, then inspect score and graph evidence."
    },
    {
      "id": "mcp-tools-list",
      "title": "Discover MCP tools",
      "intent": "Inspect the available MCP tools before calling a tool by name.",
      "surface": "MCP",
      "method": "POST",
      "endpoint": "/mcp",
      "command": "curl -X POST https://git.top/mcp -H \"content-type: application/json\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'",
      "inspect": [
        "result.tools[].name",
        "result.tools[].inputSchema"
      ],
      "trust_checks": [
        "Use require_d1 in tool arguments for strict production reads"
      ],
      "next": "Pick the tool whose name matches the Agent Map concept."
    },
    {
      "id": "mcp-get-project",
      "title": "Fetch project knowledge through MCP",
      "intent": "Use MCP when an agent runtime prefers JSON-RPC tools over direct REST calls.",
      "surface": "MCP",
      "method": "POST",
      "endpoint": "/mcp",
      "command": "curl -X POST https://git.top/mcp -H \"content-type: application/json\" -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"get_project\",\"arguments\":{\"owner\":\"cloudflare\",\"repo\":\"agents\",\"require_d1\":true}}}'",
      "inspect": [
        "result.project",
        "result.knowledge",
        "result.quality_signal_confidence",
        "result.metadata.source"
      ],
      "trust_checks": [
        "result.metadata.source=d1",
        "classification evidence",
        "quality_signal_confidence"
      ],
      "next": "Use compare_projects or get_project_graph after fetching a candidate."
    },
    {
      "id": "grp-plan-stack",
      "title": "Plan a project stack with GRP",
      "intent": "Use graph reasoning when the user asks for a plan, stack, or project set instead of one repository.",
      "surface": "GRP",
      "method": "POST",
      "endpoint": "/api/grp/query",
      "command": "curl -X POST \"https://git.top/api/grp/query?require_d1=true\" -H \"content-type: application/json\" -d '{\"goal\":\"compose an autonomous coding stack with MCP tools\",\"mode\":\"compose\",\"constraints\":{\"agent_ready\":true}}'",
      "inspect": [
        "solution_paths",
        "recommended_stack",
        "nodes",
        "edges",
        "metadata.data_source"
      ],
      "trust_checks": [
        "metadata.data_source.source=d1",
        "nodes[].repo",
        "confidence"
      ],
      "next": "Validate each recommended project with /api/project, /api/score, and /api/compare."
    }
  ],
  "trust_policy": [
    "Prefer metadata.source=d1 for production recommendations.",
    "Use require_d1=true for REST or require_d1 in MCP tool arguments when fallback data should fail closed.",
    "Cite classification evidence, quality_signal_confidence, recommendation confidence, and sync freshness.",
    "Disclose degraded sync, seed fallback, low classification confidence, or partial quality signals."
  ]
}