convez.ai
MCP ServerBusca & PesquisaAvançado
bharathvbcr

WisDev Research Runtime

bharathvbcr/WisDev

Agente de pesquisa autônoma com RAG para síntese de evidências acadêmicas

Ver no GitHub
InicialPluginScore · de 0 a 100

Agente autônomo de pesquisa em código aberto que combina Google ADK, MCP e Gemini no GCP para busca acadêmica, recuperação de evidências e síntese de resultados. Executável em terminal, com orquestração em Go e processamento opcional em Python, projetado para tarefas de pesquisa fundamentadas em fontes acadêmicas.

Instalação

$npx convez-ai bharathvbcr/WisDev

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 3 semanas
Versão
v0.1.4
Issues abertas
2
Contribuidores
1

Casos de uso

  • Pesquisa acadêmica automatizada e síntese de literatura
  • Recuperação e análise de evidências de múltiplas fontes
  • Pipelines de pesquisa guiados com validação de políticas

Veredito

Projeto robusto e bem-arquitetado para automação de pesquisa acadêmica, com suporte a RAG e políticas de token. Exige familiaridade com GCP, Go e infraestrutura em nuvem; ideal para pesquisadores e construtores que precisam de agentes autônomos baseados em evidências.

README

A tradução para o português deste README ainda está na fila.

WisDev Research Runtime

Gemini ADK MCP

Open-source autonomous research agent — Google ADK + MCP + Gemini on GCP.
Built for the Google for Startups AI Agents Challenge · Live product: ScholarLM

WisDev Research Runtime is the open-source WisDev YOLO research agent runtime and the public project identity for this extracted runtime. It is a terminal-first agent stack for planning, executing, and synthesizing evidence-grounded research tasks across academic sources.

Judge / hackathon quickstart (60 seconds)

git clone https://github.com/bharathvbcr/WisDev.git
cd WisDev
.\wisdev.cmd check
.\wisdev.cmd "What evidence supports RAG for scientific literature?"

Full submission package: docs/hackathon/SUBMISSION.md · Demo script · Architecture · Judge access

Query -> Plan -> Search -> Analyze -> Synthesize -> Report

This repository is seeded from the current WisDev runtime rather than the old archived app. The goal is to preserve current YOLO behavior first, then keep private parent-app integrations behind clean adapter boundaries.

The runtime target is Go plus optional Python only:

  • Go owns the agent, API, CLI, orchestration, search, RAG, evidence, policy, persistence, telemetry, and local validation paths.
  • Python is optional and limited to ML, LLM, embedding, PDF, and document-processing primitives.
  • Rust is intentionally excluded from this open-source project.

Contents

Architecture

graph TB
    CLI["CLI: orchestrator/cmd/wisdev"] --> Go["Go Orchestrator<br/>HTTP :8081<br/>gRPC :50053"]

    subgraph GoCore["Go Core"]
        Agent["WisDev YOLO / Guided Agent"]
        Search["Search Registry"]
        RAG["RAG + Evidence Gate"]
        Policy["Policy + Token Budgets"]
        Journal["Runtime Journal + State"]
    end

    subgraph Py["Optional Python Sidecar<br/>HTTP :8090<br/>gRPC :50052"]
        LLM["LLM Gateway"]
        PDF["PDF Extraction"]
        Embed["Embeddings"]
        Skills["Sidecar Helper Routes"]
    end

    subgraph External["External Services"]
        Academic["Academic Search APIs"]
        Models["OpenAI-compatible / Gemini / Ollama"]
        OTel["OTel Collector"]
    end

    Go --> Agent
    Agent --> Search
    Agent --> RAG
    Agent --> Policy
    Agent --> Journal
    Search --> Academic
    Go --> Py
    Py --> Models
    Go --> Models
    Go --> OTel
    Py --> OTel

Execution Loop

WisDev YOLO runs a bounded research loop:

  1. Normalize the task and infer research intent.
  2. Plan search terms and evidence targets.
  3. Retrieve papers through selected providers.
  4. Analyze and rank evidence.
  5. Synthesize a provisional answer.
  6. Evaluate coverage gaps and contradictions.
  7. Iterate until the budget is exhausted or enough evidence is available.
  8. Emit a final report, trace events, and optional persisted state.

--offline keeps the loop local and avoids external search providers, which is useful for smoke tests and CI.

Repository Layout

orchestrator/                     Go-owned runtime and API
orchestrator/cmd/wisdev/          CLI entrypoint
orchestrator/cmd/server/          HTTP/gRPC server entrypoint
orchestrator/pkg/wisdev/          Public Go embedding API
orchestrator/internal/wisdev/     YOLO, guided planning, execution, memory
orchestrator/internal/search/     Academic providers, routing, fan-out
orchestrator/internal/rag/        Retrieval, BM25, RAPTOR, evidence helpers
orchestrator/internal/evidence/   Citation and evidence utilities
orchestrator/internal/policy/     Go-local policy and validation
orchestrator/proto/               Go protobuf contracts
sidecar/                          Optional Python ML/LLM worker
config/                           Open-source config templates
adapters/scholarlm/               Private parent-app adapter notes only
docs/                             Migration status and release checklist
scripts/                          Local verification helpers

Quick Start

Windows / PowerShell

cd wisdev-agent-os
copy .env.example .env
.\scripts\verify.ps1 -StaticRelease
.\scripts\verify.ps1 -Go -PythonContract

.\wisdev.cmd --help
make install-cli

Unix-like Shell

cd wisdev-agent-os
cp .env.example .env
make test-all
make cli-help

Run a Local Offline YOLO Smoke

cd wisdev-agent-os
.\scripts\verify.ps1 -SmokeLocal

Equivalent direct command:

cd wisdev-agent-os
wisdev search --offline --max-iterations 1 "map retrieval augmented research agent evidence"

Run the Go Server

cd wisdev-agent-os\orchestrator
go run ./cmd/server

Call an Already-running Orchestrator

cd wisdev-agent-os
.\wisdev.cmd --remote "map the evidence for retrieval augmented research agents"

Run Local Mode With Selected Providers

wisdev search "map retrieval augmented research agent evidence"

The shorthand above runs the embedded Go agent locally and defaults to openalex,arxiv, so it replaces the longer form:

cd wisdev-agent-os
.\wisdev.cmd "map retrieval augmented research agent evidence"

CLI Reference

Current extracted CLI:

wisdev "question"
wisdev check
wisdev tui
wisdev demo [--offline]
wisdev mcp
wisdev setup --write .cursor/mcp.json
wisdev serve

Full CLI reference: docs/CLI.md.
MCP stdio for Cursor, Claude Code, and Codex: docs/MCP_CLIENTS.md.

Environment:

VariableDescriptionDefault
WISDEV_ORCHESTRATOR_URLHTTP base URL used by non-local CLI modehttp://127.0.0.1:8081
WISDEV_CONFIGAgent config pathconfig/wisdev.example.yaml
SCHOLAR_MODELS_CONFIGCanonical ScholarLM model config path../scholar_models.json
WISDEV_STATE_DIRLocal state directory.wisdev/state
WISDEV_JOURNAL_PATHLocal runtime journal path.wisdev/wisdev_journal.jsonl
WISDEV_LLM_BASE_URLOpenAI-compatible model endpointhttp://127.0.0.1:11434/v1
WISDEV_LLM_MODELDefault model ID for local compatible endpointsllama3.1
WISDEV_LLM_API_KEYOptional model API keyempty
PYTHON_SIDECAR_HTTP_URLOptional sidecar HTTP URLhttp://127.0.0.1:8090
PYTHON_SIDECAR_GRPC_ADDROptional sidecar gRPC address127.0.0.1:50052
TEMPORAL_ENABLEDOptional durable execution backend togglefalse

Configuration

Main config template:

agent:
  mode: yolo
  max_steps: 25
  require_approval: false
  workspace: "."

llm:
  provider: openai-compatible
  model_tier: standard
  model: "${WISDEV_LLM_MODEL}"
  api_key_env: WISDEV_LLM_API_KEY
  base_url: "${WISDEV_LLM_BASE_URL}"

storage:
  type: local
  state_dir: "${WISDEV_STATE_DIR}"
  journal_path: "${WISDEV_JOURNAL_PATH}"

execution:
  backend: local-journal
  temporal_enabled: false

sidecar:
  enabled: true
  http_url: "${PYTHON_SIDECAR_HTTP_URL}"
  grpc_addr: "${PYTHON_SIDECAR_GRPC_ADDR}"

observability:
  structured_logs: true
  otel_enabled: false
  redact_prompts: true

Model tier defaults come from the ScholarLM root scholar_models.json. When running this nested tree outside the parent checkout, set SCHOLAR_MODELS_CONFIG to the canonical model config path.

Search Providers

The Go orchestrator includes academic search provider implementations and domain routing. Common providers include:

ProviderDomain Fit
semantic_scholarGeneral academic search
openalexBroad metadata and citation graph
arxivCS, math, physics, ML preprints
pubmedBiomedical literature
europe_pmcLife sciences and biomedical full text metadata
crossrefDOI and publisher metadata
coreOpen access full text metadata
doajOpen access journals
dblpComputer science bibliography
biorxiv, medrxivBiology and medical preprints
ssrn, repecSocial science and economics
philpapersPhilosophy
nasa_adsAstronomy and astrophysics
papers_with_codeMachine learning papers and code links

Local CLI provider selection:

wisdev search "query"

For no-provider smoke tests:

wisdev search --offline "query"

Embedding API

The public Go facade lets downstream applications embed WisDev without importing internal packages:

package main

import (
    "context"
    "fmt"

    "github.com/wisdev/wisdev-agent-os/orchestrator/pkg/wisdev"
)

func main() {
    agent := wisdev.NewAgent(wisdev.WithNoSearchProviders())
    result, err := agent.RunYOLO(context.Background(), wisdev.YOLORequest{
        Task: "map open source research agent evidence",
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(result.Summary)
}

Custom search providers can be injected through wisdev.WithSearchProviders(myProvider).

API Surface

The Go server exposes unversioned route families:

Route FamilyPurpose
/health, /healthz, /readiness, /metricsHealth, readiness, Prometheus metrics
/search/*Parallel, hybrid, batch, query expansion, and tool search
/wisdev/*Planning, sessions, guided/yolo execution, research, policy, traces
/agent/yolo/*YOLO execute/status/stream/cancel compatibility surface
/rag/*RAG answer, section context, BM25, RAPTOR, hybrid retrieval
/paper/*, /papers/*PDF extraction, paper profile, count, related, network
/export/*Markdown, HTML, LaTeX export helpers
/full-paper/*, /drafting/*, /manuscript/*, /reviewer/*Long-form writing and review helpers
/vector/*, /query/*, /summarization/*, /source/*, /topic-tree/*Utility primitives
/internal/*Service-to-service operational hooks

Sidecar route families include:

Route FamilyPurpose
/ml/pdfPDF text extraction
/ml/embedEmbedding generation
/ml/bm25/*Local BM25 helper surface
/llm/generate, /llm/generate/streamLLM generation
/llm/structured-outputSchema-backed generation
/llm/embed, /llm/embed/batchRemote embedding helpers
/wisdev/deep-agents/*Internal sidecar helpers retained for Go-owned orchestration
gRPC :50052LLM service for local/container overlays

Observability

WisDev emits structured logs and supports OpenTelemetry exporters. Useful trace fields include:

  • service
  • runtime
  • component
  • operation
  • stage
  • trace_id
  • request_id
  • session_id
  • provider
  • latency_ms
  • result
  • error_code

The default local config keeps OTel disabled. Enable it with config/env once you have a collector available.

Development

Prerequisites:

ToolPurpose
Go 1.25+Orchestrator, CLI, tests
Python 3.11+Optional sidecar and Python tests
DockerOptional container validation

Common commands:

.\scripts\verify.ps1 -StaticRelease
.\scripts\verify.ps1 -Go
.\scripts\verify.ps1 -PythonContract
.\scripts\verify.ps1 -SmokeLocal

Unix-like equivalents:

make test-go
make test-python-contract
make smoke-local

Python sidecar setup:

cd sidecar
python -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements.txt
python -m pytest -q tests/unit/test_stack_contract.py

langextract is optional. PDF metadata extraction falls back to regex-only behavior when it is absent.

GitNexus Index

Initialize or refresh the GitNexus index for this sub-repo:

.\scripts\gitnexus.ps1 index
.\scripts\gitnexus.ps1 status

On Unix shells with make, you can also use:

make gitnexus-index
make gitnexus-status

Useful lookup:

gitnexus list
gitnexus context -r wisdev-agent-os -u "Property:orchestrator/internal/wisdev/workflow_agent.go:WisDevWorkflowAgent.executor"

The index is stored in .gitnexus/ and refreshed with .\scripts\gitnexus.ps1 index after code edits.

Docker

Start both services:

docker compose up --build

Services:

ServicePortsNotes
orchestrator8081, 50053Go API and internal gRPC
sidecar8090, 50052Optional Python HTTP/gRPC worker

Docker contexts have .dockerignore files to avoid copying .env, journals, caches, credentials, and local build artifacts into images.

Release Readiness

Before publishing, run:

.\scripts\verify.ps1 -StaticRelease
.\scripts\verify.ps1 -Go
.\scripts\verify.ps1 -PythonContract
.\scripts\verify.ps1 -SmokeLocal

Then follow docs/RELEASE_CHECKLIST.md.

Known local-machine limitation in this checkout: Docker validation cannot run unless Docker is installed.

Compatibility

  • adapters/scholarlm/ is documentation-only for the private parent app boundary.
  • wisdevSearchPapers is the canonical MCP tool name; legacy scholarlmSearchPapers aliases remain accepted on tools/call.
  • Migration provenance is tracked in docs/MIGRATION_STATUS.md.
  • Private app integrations, frontend auth assumptions, commerce routes, document-app routes, and Rust gateway code are not part of this open-source runtime.

License

Apache-2.0. See LICENSE and NOTICE.

Ver o original no GitHub

Bom para

Relacionados