nous

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 1, 2026 License: MIT

README

Nous

Nous is an AI coordination engine that extracts commitments from natural language, evaluates their risk of being missed, and intervenes when necessary. It acts as the "nervous system" between AI agents and human intent — tracking what was promised, scoring the likelihood of delivery, and surfacing nudges or escalations before deadlines slip.

Features

  • Commitment Extraction — Parses text (conversations, emails, notes) into structured commitments with confidence scores.
  • Risk Evaluation — Continuously scores active commitments using time-to-deadline, confidence, and external signals.
  • Intervention Engine — Automatically creates nudges, suggestions, escalations, or automation requests when risk crosses thresholds.
  • Multi-Backend Storage — Supports in-memory, SQLite, and PostgreSQL backends with identical behavior.
  • gRPC + HTTP APIs — Primary gRPC API with a lightweight REST gateway for easy integration.
  • Observability — Structured JSON logging with correlation IDs, OpenTelemetry tracing, and Prometheus-style metrics.

Quick Start

Prerequisites
  • Go 1.26+
  • (Optional) PostgreSQL 15+ for production deployments
Run Locally
# SQLite backend (default)
go run ./cmd/nous

# With explicit config
NOUS_DB_TYPE=sqlite NOUS_DB_DSN=nous.db NOUS_GRPC_ADDR=:50051 NOUS_HTTP_ADDR=:8080 go run ./cmd/nous

# PostgreSQL backend
NOUS_DB_TYPE=postgres NOUS_DB_DSN=postgres://user:pass@localhost/nous?sslmode=disable go run ./cmd/nous
Docker
docker build -t nous:latest .
docker run -p 50051:50051 -p 8080:8080 \
  -e NOUS_DB_TYPE=sqlite \
  -e NOUS_DB_DSN=/data/nous.db \
  -e NOUS_HTTP_ADDR=:8080 \
  -v nous-data:/data \
  nous:latest

Or use Docker Compose:

docker-compose up

Configuration

All configuration is via environment variables:

Variable Default Description
NOUS_GRPC_ADDR :50051 gRPC listen address
NOUS_HTTP_ADDR (empty) HTTP listen address (disabled if empty)
NOUS_DB_TYPE sqlite Database backend: memory, sqlite, postgres
NOUS_DB_DSN nous.db Connection string or file path
NOUS_TICK_INTERVAL 5m Evaluation worker tick interval
NOUS_EXTRACT_MIN_CONFIDENCE 0.0 Minimum confidence to keep extracted commitments
NOUS_RISK_OVERDUE_WEIGHT 0.6 Risk weight for overdue commitments
NOUS_RISK_DUE_SOON_WEIGHT 0.3 Risk weight for near-deadline commitments
NOUS_RISK_DUE_SOON_WINDOW 2h Window considered "due soon"
NOUS_RISK_CONFIDENCE_WEIGHT 0.2 Risk weight for low confidence
NOUS_NUDGE_THRESHOLD 0.5 Risk score to trigger a nudge
NOUS_ESCALATE_THRESHOLD 0.85 Risk score to trigger an escalation
NOUS_AUTOMATION_CONFIDENCE 0.95 Minimum confidence for automation suggestions

API

gRPC

The gRPC service is defined in api/nous/v1/nous.proto. Methods include:

  • Extract — Extract commitments from text
  • Evaluate — Run risk evaluation on active commitments
  • ListCommitments / GetCommitment — Query commitments
  • ListInterventions / GetIntervention — Query interventions
  • ResolveIntervention — Accept, reject, or execute an intervention
HTTP REST

When NOUS_HTTP_ADDR is set, the following REST endpoints are available:

Method Path Description
POST /v1/extract Extract commitments from text
POST /v1/evaluate Trigger evaluation loop
GET /v1/commitments List commitments
GET /v1/commitments/{id} Get a commitment
GET /v1/interventions List interventions
POST /v1/interventions/{id}/resolve Resolve an intervention
GET /v1/health Health/readiness check
GET /metrics Prometheus-style metrics snapshot

Architecture

cmd/nous              # Application entrypoint
api/nous/v1           # Protobuf service definitions
internal/
  domain/             # Pure domain types (commitment, intervention, decision)
  ports/              # Repository and client interfaces
  store/              # Persistence dispatch + memory/sqlite/postgres backends
  pipeline/           # Extract and Evaluate workflows
  risk/               # Risk scoring engine
  intervention/       # Intervention policy engine
  coordination/       # Direct and Axi (axi-go) kernels
  llm/                # LLM extractors (scripted MVP, pluggable)
  transport/
    grpc/             # gRPC server implementation
    http/             # REST gateway
  worker/             # Background evaluation scheduler
  observability/      # Logging, tracing, metrics, middleware
  config/             # Environment-based configuration

Testing

# Run all tests
go test ./...

# Run with PostgreSQL (requires running Postgres)
NOUS_TEST_POSTGRES_DSN=postgres://user:pass@localhost/nous_test?sslmode=disable go test ./internal/store/...

# Run end-to-end smoke test
go test ./e2e/... -v

Production Readiness

  • 12-Factor App — Config via environment, stateless processes, port binding, disposability
  • Graceful Shutdown — SIGTERM drains in-flight gRPC/HTTP requests and stops the worker
  • Health Checks — /v1/health includes readiness probe with DB connectivity check
  • Structured Logging — JSON logs to stdout with correlation IDs
  • Tracing — OpenTelemetry spans for Extract and Evaluate pipelines
  • Metrics — Atomic counters for commitments extracted, evaluations run, interventions created, risk distribution
  • Security — Distroless non-root container, no secrets in code

License

MIT

Directories

Path Synopsis
api
nous/v1
cmd
nous command
internal
adapters/chronos
Package chronos provides a gRPC adapter that wraps the Chronos gRPC client and implements ports.ChronosClient.
 Package chronos provides a gRPC adapter that wraps the Chronos gRPC client and implements ports.ChronosClient.
adapters/mnemos
Package mnemos provides a gRPC adapter that wraps the Mnemos service client and implements ports.MnemosClient.
 Package mnemos provides a gRPC adapter that wraps the Mnemos service client and implements ports.MnemosClient.
circuit
Package circuit implements a simple circuit breaker pattern for protecting external service calls.
 Package circuit implements a simple circuit breaker pattern for protecting external service calls.
config
Package config loads Nous runtime configuration from environment variables with sensible defaults for development.
 Package config loads Nous runtime configuration from environment variables with sensible defaults for development.
coordination
Package coordination is the Decision -> Action boundary of Nous.
 Package coordination is the Decision -> Action boundary of Nous.
domain
Package domain holds the pure types of the Nous coordination layer.
 Package domain holds the pure types of the Nous coordination layer.
intervention
Package intervention decides whether to interrupt the user (or trigger an automation) based on a risk assessment.
 Package intervention decides whether to interrupt the user (or trigger an automation) based on a risk assessment.
llm
Package llm holds the LLM-backed coordination surfaces of Nous.
 Package llm holds the LLM-backed coordination surfaces of Nous.
observability
Package observability provides cross-cutting concerns: structured logging with correlation IDs, OpenTelemetry tracing, and Prometheus-style metrics.
 Package observability provides cross-cutting concerns: structured logging with correlation IDs, OpenTelemetry tracing, and Prometheus-style metrics.
pipeline
Package pipeline orchestrates the cross-aggregate workflows of the Nous engine.
 Package pipeline orchestrates the cross-aggregate workflows of the Nous engine.
ports
Package ports declares the outbound interfaces ("ports") the Nous engine drives.
 Package ports declares the outbound interfaces ("ports") the Nous engine drives.
risk
Package risk computes the likelihood that a commitment or task will be missed.
 Package risk computes the likelihood that a commitment or task will be missed.
store
Package store wires the configured persistence backend into the Nous engine.
 Package store wires the configured persistence backend into the Nous engine.
store/memory
Package memory is the in-process backend for Nous repositories.
 Package memory is the in-process backend for Nous repositories.
store/postgres
Package postgres is the PostgreSQL-backed implementation of the Nous repositories.
 Package postgres is the PostgreSQL-backed implementation of the Nous repositories.
store/sqlite
Package sqlite is the SQLite-backed implementation of the Nous repositories.
 Package sqlite is the SQLite-backed implementation of the Nous repositories.
transport/grpc
Package grpc implements the Nous gRPC service handlers.
 Package grpc implements the Nous gRPC service handlers.
transport/http
Package http exposes a lightweight HTTP surface over the Nous gRPC service.
 Package http exposes a lightweight HTTP surface over the Nous gRPC service.
worker
Package worker runs the Nous evaluation loop on a configurable tick.
 Package worker runs the Nous evaluation loop on a configurable tick.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.