Skip to content

README.md

Latest commit

 

History

History
224 lines (173 loc) · 9.14 KB

README.md

File metadata and controls

224 lines (173 loc) · 9.14 KB
Raw

AInsel

AInsel adds AI agents to the systems your team already uses.

Administrators wire AI into existing tools — code forges, ticket systems, email, anywhere events happen — by configuring agents, triggers, and personas. End users keep using their tools as they always have, and the AI shows up where it helps: a review comment, an issue label, a draft reply. The AI specifics — which model, which prompts, which tools — stay with the administrator.

Why this matters

AI is now table stakes for engineering productivity, but operating it well is hard. Prompt engineering, model selection, tool design, and token budgets are full-time concerns — you can't make every team member an AI expert, and you don't want each team improvising independently. Costs need central management. Quality needs central guardrails. Existing tools shouldn't have to change.

AInsel solves this by putting AI knowledge in one place: administrators configure the agents (model, persona, tools, triggers) once; end users keep using their existing tools and benefit from the AI through normal artifacts. The expertise stays centralized; the value spreads everywhere.

Who this is for

End users. People already using the systems AInsel integrates into — Forgejo today, more connectors as they land. They don't have to know AInsel exists. They see normal artifacts: a review comment on their PR, a label on their issue, a draft reply on a thread. They never pick a model, never write a prompt, never see a token count.

Administrators. The locus of AI expertise for the organization. They configure agents (model, persona, tools), define triggers that decide when agents fire, and connect AInsel to the source systems their teams use. They own cost management, quality guardrails, and incident response. The administrator guide is written for this role.

Platform contributors. Engineers who extend AInsel itself — writing new connectors, adding new tools, fixing operator behavior. Start with CONTRIBUTING.md and AGENTS.md; the per-package READMEs under services/, operators/, shared/, pi/, chart/, and frontend/ describe each component in detail.

What you can do with it

Today, via the webhook connector

The generic WebhookConnector is the only end-to-end wired source today (configured for Forgejo). With it you can:

  • AI code review on PRs. An agent comments on newly opened pull requests with file-level feedback on the changed lines, focused on the criteria you configure in the persona.
  • Issue triage and labeling. An agent classifies incoming issues, applies labels (priority, area, type), and optionally summarizes or asks clarifying questions.
  • Comment Q&A. An agent watches issue and PR comments for mentions or commands and replies with focused, scoped answers — not a freeform chatbot.
  • Issue → PR implementation. An agent picks up issues with a trigger label, branches, writes the change, and opens a PR back for review.

With your own connector

The connector is the extension point. AInsel emits a canonical event stream regardless of source (see docs/event-schema.md), so anywhere events happen — Office365 mailboxes, Jira tickets, Slack channels, a proprietary CI system — can become an AInsel source. The agents, triggers, and personas stay the same; only the connector changes.

A new connector is two parts: a Kubernetes operator that watches a new connector CRD and reconciles webhook subscriptions + a Deployment, and a service that translates the source's native event format into the canonical event schema before POSTing to the hub. The webhook connector under services/webhook-receiver/ and operators/event-gateway/ is the reference implementation. Writing one is a contributor task — see CONTRIBUTING.md and the connector developer tutorial.

Office365, Jira, and Slack are illustrative possibilities, not commitments. The roadmap tracks what's actually scheduled.

How it works (conceptually)

A connector turns external events (webhooks, polled APIs) into a canonical event stream. The hub reads that stream and matches each event against admin-defined triggers — a trigger says "when an event of this type matches these filters, invoke this agent". Matched events go to agents, which are AI workers configured with a model, a persona, and a set of tools. The agent decides what to do and acts back on the source system through its tools (commenting on a PR, labeling an issue, opening a draft).

Administrators control the agents, triggers, and personas. End users see only the result — a comment, a label, a reply — appearing in the tool they were already using.

Architecture

graph TD
    FORGE[Forgejo Instance] -->|webhook POST| FC[services/webhook-receiver]

    subgraph "PostgreSQL Event Queue"
        EQ[(events + agent_tasks<br/>tables)]
    end

    FC -->|POST /internal/events| HUB[services/hub]
    HUB -->|insert| EQ
    EQ -->|poll + match| HUB
    HUB -->|enqueue tasks| EQ
    EQ -->|long-poll| AR1[agent runtime<br/>code-reviewer]
    EQ -->|long-poll| AR2[agent runtime<br/>issue-triager]
    AR1 -->|ACK/NACK| HUB
    AR2 -->|ACK/NACK| HUB

    AR1 -->|API calls| FORGE
    AR2 -->|API calls| FORGE

    subgraph "Kubernetes Control Plane"
        AO[operators/agent]
        CO[operators/event-gateway]
        K8s[(Kubernetes API<br/>CRDs)]
    end

    AO -->|watches Agent + Trigger| K8s
    CO -->|watches WebhookConnector| K8s
    AO -->|manages Deployments| AR1
    AO -->|manages Deployments| AR2
    CO -->|manages Deployment| FC

    UI[frontend] -->|REST API| HUB
    HUB -->|CRUD| K8s

    subgraph "Vector Database"
        QD[(qdrant)]
    end

    AR1 .-.->|store/recall| QD
    AR2 .-.->|store/recall| QD
Loading

For the full data flow, NATS subjects, CRD relationships, and deployment topology, see docs/architecture.md.

Repository layout

Path Language Purpose
frontend/ TypeScript Operations console (React + Vite)
services/hub/ Go Control plane: event routing, REST API
services/webhook-receiver/ Go Generic webhook receiver, event normalizer
services/mcp/ Go MCP server registry
operators/agent/ Go K8s operator for Agent + Trigger CRDs
operators/event-gateway/ Go K8s operator for WebhookConnector CRD
shared/api/ Go Shared event schema, filter engine
chart/ Helm Single chart deploying the whole platform
pi/ JavaScript Pi-native agent runtime
docs/ — Architecture, CRDs, deployment

Each top-level folder has its own README.md with package-specific details.

Quick start

Requires Node.js 20+, pnpm 9.15+, and Go 1.26+.

pnpm install                  # install frontend deps (workspace root)
pnpm --filter frontend dev    # frontend dev server
go build ./...                # build every Go module in the workspace
go test ./...                 # run every Go test

Go modules are joined via go.work. Each Go subdirectory has its own go.mod; changes in shared/api/ are picked up by downstream modules automatically at build time.

Where to go next

For administrators:

For evaluators:

  • This README — value prop, stakeholders, use cases
  • docs/architecture.md — full technical architecture, data flow, NATS streams

For platform contributors:

Reference:

AI full disclosure

AInsel is developed with extensive AI assistance. This project is itself a platform for AI agents, and its own development runs on them: issues are refined, implemented, tested, and code-reviewed by AI agents working under the rules in AGENTS.md. Humans lead the ideas, architecture, verification, and release decisions. We say this openly because it shaped how the project was built, and because an AI platform should be honest about using AI.

License

This project is licensed under the Apache License 2.0.