NovaOps Company Brain

NovaOps Company Brain is a permission-sensitive operational system with four workflows: Maya for HR/onboarding, Webex for IT access operations, standalone Vendor CRM extraction, and an offline Renewal process. It combines cited document retrieval, SQLite-backed operational records, an MCP tool boundary, Bedrock Nova 2 Lite structured output and answers, durable approval gates, Langfuse evaluation traces, and containerized entry points.

The repository is self-contained. Its company records and documents are synthetic and live under novaops-enterprise-agent-dataset/.

What is implemented

Related MCP server: Corporate Tools MCP Server

Architecture

CompanyBrainAgent owns routing and the shared conversational result contract. Maya and Webex remain focused internal scopes. Vendor is a synchronous document-in/record-out function; Renewal begins from a schedule and resumes on persisted inbound events. All conversational retrieval and operational calls cross a ToolGateway, which can run in-process for deterministic tests or against the FastMCP server. SQLite is the source of durable operational, approval, renewal, outbox, and idempotency state; the default database is .state/novaops.sqlite3 and can be overridden with NOVAOPS_DB_PATH.

The dataset deliberately has no employee-to-Webex-seat relationship. Role entitlement is not proof of assignment, so inspect_software_seat_assignments returns that limitation explicitly.

Install and verify

Python 3.11 or newer is required.

git clone https://github.com/eddieiskl/novaops-company-brain.git
cd novaops-company-brain
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
python -m pytest -q

Run the committed deterministic evaluations:

python evals/run_maya_s2.py
python evals/run_maya_s9.py
python evals/run_webex_s8.py
python evals/run_submission.py
python evals/run_submission.py --include-optional
python evals/run_guardrail_attacks.py

The submission runner maps every required measured input to binding expectations from spec/GOLDEN-DATASETS.json or an explicit Webex check. It exits non-zero when a required fact/source, permission rule, tool-use rule, or generic safety invariant fails.

MCP and live model mode

Start the MCP server in one terminal:

source .venv/bin/activate
python retrieval_mcp_server.py

Smoke-test it from another:

source .venv/bin/activate
NOVAOPS_TOOL_MODE=mcp python scripts/smoke_mcp.py

For a traced Bedrock run, create a local .env or export credentials for AWS and Langfuse, then run:

NOVAOPS_TOOL_MODE=mcp NOVAOPS_ANSWER_MODE=bedrock \
  python evals/run_submission.py --include-optional --trace --update-submission

This sends synthetic evaluation prompts and retrieved synthetic NovaOps evidence to the configured AWS Bedrock and Langfuse projects. Never commit .env; it is ignored.

Evaluation and observability

Each measured turn creates one Langfuse trace—27 for required scope and 33 with both optional workflows. Multi-turn trace inputs include prior conversation, declared evaluation criteria, and the evidence or verified operation state used by the answer. Large source documents stay in observation inputs rather than propagated metadata. The phase and tool observations wrap live execution, and tool observations record real arguments, results, completion state, and errors. Bedrock answer and structured-extraction calls appear as generation observations. Deterministic score comments explain every result rather than reporting an unexplained aggregate pass.

The bounded improvement record is in evals/IMPROVEMENT_REPORT.md. The final trace IDs and reviewed commit are recorded in SUBMISSION.md.

GitHub Actions runs pytest, the optional-inclusive 33-case promotion gate, the focused guardrail attacks, Compose validation, and a build of all three container images.

Completion status

Security and data handling

• Secrets and runtime databases are ignored by Git.

• Regular employees never receive manager-only chunks.

• Direct write tools are absent from Maya’s model-visible loadouts.

• A recorded, assigned human approval is required before a gated write can be released.

• Answers distinguish observed facts, actions taken, recommendations, and blockers.

See SUBMISSION.md for the deliverable index and spec/PROJECT-DESCRIPTION.md for the supplied project brief.

Containers

IMAGE_TAG="$(git rev-parse HEAD)" docker compose build
IMAGE_TAG="$(git rev-parse HEAD)" docker compose up -d
curl http://127.0.0.1:18080/health/live
curl http://127.0.0.1:18080/health/ready

See docs/deployment.md for entry points, durability, credentials, and cloud-deployment boundaries.