convez.ai
AgenteEscrita & ConteúdoAvançado
PouyanJay

Lunaris — Engine de Síntese Agentico de Cursos

PouyanJay/lunaris

Gera cursos verificados com pré-requisitos garantidos e claims comprovados

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent que transforma um tópico em um curso completo e verificado, com ordenação determinística de pré-requisitos e comprovação de claims contra evidências. Utiliza grafos de pré-requisitos, estrutura Merrill e citações rastreáveis para garantir coerência pedagógica e rigor factual.

Instalação

$npx convez-ai PouyanJay/lunaris

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
8
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v0.2.1
Issues abertas
21
Contribuidores
1

Casos de uso

  • Criar currículos estruturados de tópicos técnicos ou acadêmicos
  • Gerar conteúdo educacional com ordenação automática de conceitos
  • Produzir cursos com claims auditáveis e fontes citadas

Veredito

Lunaris é uma arquitetura séria de síntese de conteúdo educacional com moats técnicos reais (grafos acíclicos, verificação de claims). Projeto ambicioso que endereça problemas reais de geração de cursos, mas exige infraestrutura pesada (LangGraph, Supabase, Claude) e é mais ferramenta de plataforma que plugin plug-and-play.

README

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

Lunaris

Turn a topic into a real, verified course — built by an agent, guaranteed by code.

Type a subject. An agent plans the curriculum, writes the lessons, orders every prerequisite, and grounds every factual claim against evidence — then hands you a prerequisite map, Merrill‑structured lessons, branded diagrams, and claims that carry their sources.

License: AGPL v3 Python 3.12 React 19 FastAPI Supabase pgvector Deep Agents Claude

Why it exists · Architecture · Pipeline · Quick start · Configuration · Docs


Why it exists

Most "AI course generators" free‑hand an answer in one shot — plausible, unordered, and unsourced. Lunaris keeps two correctness guarantees in deterministic code, exposed to the agent as tools so the model cannot talk its way past them:

Failure modeThe moat
AA concept is taught before its prerequisitesA prerequisite‑graph builder guarantees an acyclic, topologically‑ordered curriculum
BAn unsupported claim ships as factA claim‑level verifier grounds every factual sentence against retrieved evidence and cuts what it can't support

The agent reasons about what to do next; the moats and a deterministic finalize step guarantee what ships.

Relevant, not just correct

Ordering and grounding don't make a course about the right thing at the right level. Ask for "Improve my English to CLB 10" (an advanced band) and a naive generator starts from "the English alphabet" — coherent, correctly ordered, and useless. So Lunaris runs the front of the pipeline a good tutor runs first: interpret the request into a typed goal‑for‑a‑learner brief → research the real standard → model the learner's frontier (what to skip) → scope to the gap → design backward and curate vetted resources. The moats then operate over relevant, scoped input. → relevance.md

Grounded, and auditable

Grounding isn't a binary check. Every source carries a trust tier (official / reputable / open / blocked, plus vouched for sources you supply), a source type, and a credibility score — constructed at acquisition and shown on the citation. On a high‑risk course the verifier applies a risk‑tiered trust floor: evidence must be curated‑or‑better and credible, or corroborated across ≥2 independent domains — otherwise the claim is cut. Authority emerges from agreement, not from a label (and the LLM judges stay blind to source labels while you see the full trust). → grounding.md

Architecture

A conventional product surface (web + API + Supabase) wraps an agentic core: a deep‑agent harness plans the build and calls every capability — including the two deterministic moats — as tools.

flowchart TB
    subgraph Surface["🖥  Product surface"]
        WEB["Web studio<br/>React 19 · Vite"]
        API["API<br/>FastAPI · SSE stream"]
    end
    subgraph Agentic["🤖  Agentic core"]
        HARNESS["Deep-agent harness<br/>create_deep_agent · plans + calls tools"]
        SUB["Lesson authoring subagent<br/>author → verify → revise · LangGraph"]
        MCP["MCP registry<br/>FastMCP — moats as portable tools"]
    end
    subgraph Moats["🛡  Deterministic moats — exposed as tools"]
        GRAPH{{"Prerequisite graph<br/>acyclic · topological order"}}
        VERIFY{{"Claim verifier<br/>risk-tiered trust floor"}}
    end
    subgraph Data["📚  Data + grounding"]
        DISC["Shared discovery<br/>search · extract · domain trust"]
        PG[("Supabase<br/>Postgres · pgvector · RLS")]
    end

    WEB <-->|"authedFetch · SSE"| API
    API --> HARNESS
    HARNESS --> SUB
    HARNESS -->|tool call| GRAPH
    HARNESS -->|tool call| VERIFY
    SUB -->|grounds each claim| VERIFY
    HARNESS --> DISC
    VERIFY -->|retrieves evidence| PG
    DISC -->|ingests sources| PG
    HARNESS -.also exposed via.-> MCP
    MCP --> GRAPH
    MCP --> VERIFY

    classDef moat fill:#3b2f10,stroke:#e8a33d,stroke-width:2px,color:#fff;
    class GRAPH,VERIFY moat
LayerPackage / appWhat it owns
Agent harnesspackages/agent · lunaris_agent.harnesscreate_deep_agent planner; runs the relevance front, calls the moat tools, delegates Merrill authoring to the LangGraph author → verify → revise subagent. Default pipeline (LUNARIS_PIPELINE=agent).
Prerequisite moatpackages/graph · PrerequisiteGraphBuilderPairwise prereq judgements assembled into a guaranteed‑acyclic, minimal‑edge, topologically‑ordered graph.
Grounding moatpackages/grounding · Verifier + PgVectorRetrieverPer‑claim evidence retrieval (pgvector + Voyage) and an independent support assessor with the trust floor; nothing unsupported ships.
Shared discoverypackages/grounding.discoveryOne search provider (Tavily) + extractor (Trafilatura) + domain‑trust model, shared by research and resource curation; key‑gated, deterministic stubs otherwise.
MCP registrylunaris_agent.mcp_registryThe two moats as portable FastMCP tools (build_prerequisite_graph, verify_claims).
Runtimepackages/runtimePydantic course schema, persistence, structlog logging (correlation IDs + redaction), resilience + credential seams.
APIapps/api · FastAPICourse create + SSE build stream, live agent transcript, corpus, capabilities, per‑tenant credentials.
Webapps/web · React 19Studio: run‑history sidebar, live build timeline, lesson Reader, prerequisite Map, Corpus + Settings.
Evalpackages/eval · lunaris-evalIndependent, offline checkers for the definition of done (prereq order + factuality).

The model provider is Anthropic Claude (a strong + worker tier); embeddings are Voyage AI. Full system design, sequence, and deployment diagrams: documentation/architecture.md.

The build pipeline

Every stage is a tool the planning agent calls, writing its typed result onto a shared CourseDraft. Two stages (◆) are the deterministic moats.

flowchart LR
    A["interpret<br/>request"] --> B["research<br/>standard"] --> C["model<br/>learner"] --> D["extract<br/>concepts"]
    D --> E{{"prerequisite<br/>graph ◆"}}
    E --> F["design<br/>curriculum"] --> G["seed +<br/>discover grounding"]
    G --> H["author<br/>lessons"] --> I{{"verify<br/>claims ◆"}}
    I --> J["curate<br/>resources"] --> K["coverage<br/>gate"] --> L(["📘 Course"])

    classDef moat fill:#3b2f10,stroke:#e8a33d,stroke-width:2px,color:#fff;
    class E,I moat

Step‑by‑step, traced on a worked example: documentation/build-pipeline.md.

Quick start

One command, from a fresh clone:

make run

This installs everything (uv + the Python workspace + web deps), brings up Supabase + the API + the web dev server, and opens the studio. Pipeline selection is automatic: with a reachable ANTHROPIC_API_KEY (in .env or the in‑app Settings) it serves the real agent harness; with no key it falls back to the deterministic stub pipeline (instant, always works) and says so. Force a mode with LUNARIS_PIPELINE=agent|live|stub.

make            # command reference
make start      # backend only (Supabase + API)
make stop       # tear down (Supabase data preserved)
make test       # Python + web suites
make lint       # ruff + typecheck + eslint gates

Configuration

Configuration lives in .env (copied from .env.sample on first run). Every external key is optional — each unlocks a live capability and its absence falls back to a deterministic stub, so the no‑key path always works:

KeyUnlocksAbsent
ANTHROPIC_API_KEYLive Claude — the agent/live pipelines, the relevance front, every -m evalThe deterministic stub pipeline (or a keyless Draft tier — see below)
SEARCH_API_KEY (Tavily)Standard research + curated per‑lesson resources (metered, per‑build budget)research: unavailable, no resources — still builds at the right level
YOUTUBE_API_KEYRicher video resources (duration / channel)Video candidates via the shared search
EMBEDDINGS_API_KEY (Voyage) + SupabaseReal pgvector grounding → claim‑level citationsThe verifier fails safe (cuts every claim → Needs review)

Keyless Draft mode. An account with no keys can still build end‑to‑end in a labelled Draft tier backed by fully self‑hosted fallbacks (a local Qwen LLM + BGE embeddings + DuckDuckGo search) — degraded quality, clearly marked, no third‑party key required.

Documentation

Full docs live in documentation/ — start there for the index. The pages:

DocRead it for
getting-started.mdA hands‑on first build, step by step
architecture.mdSystem‑design and sequence diagrams (Mermaid)
build-pipeline.mdThe 11‑stage build, traced on a worked example
relevance.mdThe interpret → research → scope front + its cost model
grounding.mdTrust tiers, the trust floor, the three corpus modes
deployment.mdProduction topology, BYOK, and the keyless Draft tier

Development

  • Backend: uv run pytest -q (deterministic, no key) · uv run ruff check . && uv run ruff format --check .
  • Web: cd apps/web && npm run dev (or test / lint / typecheck / build)
  • Live evals (real key): uv run --env-file .env pytest -m eval -q
  • Score a course vs the definition of done: uv run lunaris-eval <course.json>

Project‑internal engineering standards, agents, and skills live under .claude/ (gitignored) and are not shipped with the product.

License

GNU AGPL‑3.0 © Pouyan Jahangiri

Ver o original no GitHub

Bom para

Relacionados