Nakima — Engineering Intelligence Platform

Autonomous AI GitHub App — analyzes repositories, plans changes, generates code, validates quality, and opens pull requests from issues. Production-grade, security-first.

What Is Nakima?

Nakima is a self-hosted GitHub App that turns GitHub Issues into validated Pull Requests — automatically. It combines:

Repository Intelligence — AST-based code analysis, dependency graphs, health scoring
AI Orchestration — multi-provider LLM planning, code generation, and review
Security Intelligence Layer (NSIL) — secret detection, SAST, DAST, dependency audits, and optional penetration-test simulation
Nakima Engineering Intelligence System (NEIS) — reasoning engine with cognitive, evidence, decision, and arbitration sub-engines
Quality Gate — test coverage enforcement before any PR is opened
Engineering Intelligence Reports — PDF reports covering decisions, events, and findings

Using Nakima: Install the GitHub App (once publicly launched) from github.com/apps/nakima. You do not need to self-host. See the User Guide.

Source code: Available for audit only. See LICENSE for permitted use.

Architecture Overview

GitHub Issue
     │
     ▼
┌─────────────────────────────────────────────────────┐
│                  GitHub App (Webhook)                │
│           githubapp/  ←  HMAC verified               │
└─────────────────┬───────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────┐
│              AI Orchestrator                        │
│   orchestrator/workflow.py                          │
│   ┌──────────────────────────────────────────────┐  │
│   │   Planner → Implementer → Validator → PR     │  │
│   └──────────────────────────────────────────────┘  │
└───┬──────────┬──────────────┬───────────────────────┘
    │          │              │
    ▼          ▼              ▼
 Agents    Repository     Security
 agents/   repository/    security/nsil.py
           analysis.py    (NSIL — all 4 gates)
    │          │              │
    ▼          ▼              ▼
 Providers  Memory/Graph   NEIS Reasoning
 providers/ memory/        neis/reasoning/
 (GitHub    knowledge      cognitive, evidence,
  Models,   graph          decision, arbitration
  Claude,                  engines
  OpenAI)
    │
    ▼
 Execution Sandbox
 execution/ (Docker-isolated)

Core Features

Feature	Description
Issue → PR automation	Reads an issue, plans implementation steps, generates code, validates, opens PR
NEIS Reasoning	Four-engine reasoning: cognitive modelling → evidence gathering → decision synthesis → arbitration
NSIL Security	Secret scan + config scan + SAST (bandit) + dependency audit (safety) + DAST + pentest simulation
Repository health	AST analysis, complexity scoring, dependency graph, tech stack detection
AI provider agnostic	GitHub Models (free default), Anthropic Claude, OpenAI GPT-4, DeepSeek
Engineering reports	PDF reports with decision registry, event log, and security findings
Document upload	Ingest PDF/DOCX context documents for repository-aware Q&A
Quality Gate	Blocks PRs when source changes have no accompanying test changes
Virus scanning	ClamAV integration for uploaded documents
Command Centre	Real-time dashboard at `/`

Quick Start (Self-Hosted)

Prerequisites: Docker ≥ 24, Docker Compose ≥ 2.20, a GitHub App with issues: read, contents: write, pull_requests: write permissions.

# 1 — Clone
git clone https://github.com/cirvannaco-png/Nakima.git
cd Nakima

# 2 — Configure
cp .env.example .env
# Fill in GITHUB_APP_ID, GITHUB_PRIVATE_KEY_PATH, GITHUB_WEBHOOK_SECRET, GITHUB_TOKEN

# 3 — Build & start
docker compose up --build -d

# 4 — Run migrations
docker compose exec app alembic upgrade head

# 5 — Verify
curl http://localhost:8000/health

The Command Centre dashboard is at http://localhost:8000/. API docs (Swagger) are at http://localhost:8000/docs.

Documentation

Guide	Description
Architecture Guide	System design, data flow, component responsibilities
Installation Guide	Prerequisites, setup, configuration
Deployment Guide	Docker, cloud (GCP/AWS), env vars, health checks
API Reference	All REST endpoints with request/response schemas
Developer Guide	Dev setup, coding standards, branching, contribution
User Guide	Using the GitHub App end-to-end
Testing Guide	Unit, integration, E2E, coverage requirements
Security Guide	Secrets, auth, NSIL, dependency policy
Operations Guide	Monitoring, logging, incident response, scaling