Intelis-Agent

Intelis-Agent

A self-running research agent that monitors the web on a schedule, verifies findings with LLM analysis, and delivers intelligence reports by email and in-app.

[CI] [License: MIT] [TypeScript] [React] [Tests]

Live demo · Report a bug · Request a feature · Changelog

Table of Contents

• About Intelis-Agent
• Architecture
• Tech Stack
• Getting Started
• Usage
• API Reference
• Project Structure
• Features and Limitations
• Testing
• Deployment
• Contributing
• Security
• License
• Acknowledgments
• References

About Intelis-Agent

Intelis-Agent is a full-stack research application. A user describes a research objective in natural language, selects one or more implemented sources, and configures a five- or six-field cron expression. The server stores the task, collects candidate material, processes the research pipeline, persists findings and run state, and creates intelligence reports.

The application is built around traceable findings. Each finding can retain its source URL, source name, excerpt, summary, quality score, relevance score, credibility score, novelty score, and verification status. Ask Mode queries stored findings and returns citations for the records used in the answer.

Implemented capabilities

• Natural-language research tasks with optional keywords, topics, filters, source selection, and scheduled execution.
• Web, RSS, and NewsAPI source collection implemented in server/intelis/sources.ts.
• LLM-backed task-signal derivation, finding analysis, report synthesis, semantic retrieval, and Ask Mode through Groq’s llama-3.3-70b-versatile model.
• Persisted research runs, stage state, findings, source snapshots, trends, reports, delivery events, and audit logs.
• Manual Run now execution, task pause/resume controls, and scheduler activation handling.
• Summary, digest, and alert reports with in-app notifications and optional Resend email delivery.
• Followed entities for companies, people, and topics, with change events and trend analysis.
• Client-side PDF and CSV export utilities, task filtering, collections, and theme preferences.

Architecture

flowchart LR
  UI[React + Vite client]
  API[Express + tRPC server]
  AUTH[OAuth-backed JWT sessions]
  PIPE[Research pipeline]
  SRC[Web / RSS / NewsAPI]
  LLM[Groq LLM]
  DB[(MySQL + Drizzle ORM)]
  EMAIL[Resend]
  CRON[Heartbeat scheduler]

  UI --> API
  API --> AUTH
  API --> DB
  API --> PIPE
  CRON -->|POST /api/scheduled/research-run| PIPE
  PIPE --> SRC
  PIPE --> LLM
  PIPE --> DB
  PIPE --> EMAIL

The application entry point is server/_core/index.ts. It registers the Express body parsers, OAuth callback, storage proxy, scheduled research endpoint, and tRPC router at /api/trpc. Development mode uses Vite middleware. Production mode serves the client build from the server process.

Tech Stack

Getting Started

Prerequisites

Use Node.js 22 and pnpm. Node.js 22 is the runtime validated by the repository’s CI workflow. Local development also requires a reachable MySQL-compatible database and credentials for the integrations used by your environment.

Installation

git clone https://github.com/vincenzo-afk/Intelis-Agent.git
cd Intelis-Agent
pnpm install
cp .env.example .env

Generate a development secret with:

openssl rand -hex 32

Apply the database migrations with the repository’s script:

pnpm db:push

Configuration

The complete template is in .env.example. Never commit .env, session tokens, API keys, or database credentials.

Run locally

pnpm dev

The server prefers http://localhost:3000/. If that port is occupied, it checks the next available ports.

For a production-style local run:

pnpm build
pnpm start

Usage

After authentication, create a research task from the dashboard. The task input supports a name, a natural-language request, at least one source, optional keywords and topics, source filters, a cron expression, an execution profile, and optional email delivery.

A research request can be written in plain language, for example:

Monitor changes in open-weight language models released during the past week, focusing on benchmark performance and model size.

The task router validates the request with Zod. It accepts web, rss, and news_api sources; scheduled and high_throughput execution profiles; and five- or six-field cron expressions. Tasks can be run immediately, paused, resumed, updated, or removed.

Ask Mode answers questions from stored findings rather than from an unrestricted prompt. Responses include citations containing the finding ID, title, and source URL.

API Reference

The API is a tRPC router mounted at /api/trpc. Protected procedures require a valid authenticated session. The server accepts the session cookie and an Authorization: Bearer fallback for environments where cookies are unavailable.

tRPC procedures

Scheduled research endpoint

POST /api/scheduled/research-run is reserved for authenticated scheduler callbacks. The handler requires a cron identity and task UID, returns 403 to non-cron callers, skips inactive or orphaned tasks, and starts the research pipeline for valid scheduled tasks.

The scheduler credential is deployment-specific. Keep it in the hosting platform’s secret manager and never expose it in client code.

Project Structure

Intelis-Agent/
├── client/                 # React client, pages, components, styles, and exports
├── server/
│   ├── _core/              # Express bootstrap, auth, tRPC, storage, Vite, and platform adapters
│   ├── intelis/             # Sources, Groq analysis, pipeline, scheduling, repository, and validators
│   ├── routers/             # tRPC feature routers
│   └── *.test.ts            # Server tests
├── shared/                  # Types and constants shared by client and server
├── drizzle/                # Drizzle schema and SQL migrations
├── patches/                # pnpm patched dependency sources
├── index.ts                 # Root host entry that imports the Express bootstrap
├── package.json             # Scripts and dependency declarations
├── pnpm-lock.yaml           # Locked dependency graph
├── tsconfig.json            # TypeScript configuration
├── vite.config.ts           # Client build configuration
├── vitest.config.ts         # Test configuration
└── vercel.json              # Static asset cache header configuration

The main persisted entities are defined in drizzle/schema.ts: users, collections, research tasks, followed entities, change events, runs, findings, source snapshots, trends, reports, Ask Mode conversations and messages, delivery events, and audit logs.

Features and Limitations

Implemented

• Scheduled and manual research task execution.
• Web, RSS, and NewsAPI collection.
• LLM-based signal derivation, analysis, summarization, semantic retrieval, and grounded answers.
• Persisted run progress, findings, scores, verification status, reports, trends, and delivery events.
• In-app notifications and optional Resend email delivery.
• PDF and CSV export utilities.
• Task, collection, entity, dashboard, and theme interfaces.

Current limitations

The repository does not contain a Dockerfile or Docker Compose configuration. The vercel.json file defines an asset-cache header but does not provision a database, environment variables, or a scheduler. On hosts without the Manus heartbeat service, tasks may require deployment-specific scheduler integration for autonomous execution; manual runs remain available.

Testing

Run the checked-in scripts:

pnpm check
pnpm test
pnpm build

The suite uses Vitest and covers client utilities, authentication logout, source collection, contracts, validators, Groq behavior, pipeline progress, email delivery, provider credentials, and intelligence task controls. The default run contains 29 tests; the live Groq, NewsAPI, and Resend checks are skipped when their credentials are not present.

Formatting is available with:

pnpm format

The GitHub Actions workflow runs dependency installation, pnpm check, pnpm test, and pnpm build in a Validate job on Node.js 22.

Deployment

Self-hosted Node.js

pnpm install --frozen-lockfile
pnpm db:push
pnpm build
NODE_ENV=production pnpm start

Set the required environment variables before starting the server. Add an external scheduler that can authenticate to /api/scheduled/research-run when scheduled research is needed outside the Manus heartbeat environment.

Vercel

The repository contains vercel.json with a long-cache header for /assets/(.*). It does not declare builds, functions, routes, database provisioning, or cron configuration. Verify the selected Vercel runtime and scheduling model before treating a deployment as fully autonomous.

Contributing

Read CONTRIBUTING.md before opening a pull request. The normal workflow is:

pnpm install
pnpm check
pnpm test
pnpm build

Keep changes focused, preserve server-side secret handling, update documentation when behavior changes, and do not commit .env files, tokens, private research material, production data, or generated build output. Use the issue forms and pull-request template in .github/.

Security

The application signs and verifies session JWTs, validates tRPC inputs with Zod, checks task ownership before protected mutations, separates cron identities from regular users, and keeps provider credentials on the server. The scheduled endpoint rejects non-cron callers with HTTP 403. Research-source content is treated as untrusted reference material by the LLM prompts.

Report vulnerabilities privately through the GitHub security advisory form when available. If private advisories are unavailable, contact the maintainer through the repository owner’s GitHub profile without posting exploit details publicly. See SECURITY.md.

License

Intelis-Agent is licensed under the MIT License.

Acknowledgments

Intelis-Agent uses open-source libraries and services including React, Vite, Express, tRPC, Drizzle ORM, Groq, Resend, NewsAPI, the AWS SDK for JavaScript, Radix UI, and Vitest. See package.json and the lockfile for the dependency sources and versions.

References