https://open-reliability.com/polaris

Open Reliability's workspace powered by Polaris, an AI Reliability Agent that guides engineers through data-driven analysis, maintenance strategy optimisation, and reliability decision-making in a local-only deployment.

Polaris Agent can select and execute registered specialist capabilities through a bounded sequential multi-call loop. Master Data, Defect Elimination, and Maintenance Strategy are the active registered specialists; Reliability Improvement remains future-development code.

This codebase is configured for local deployment only.

Sample Demo

Reliability Agent Workflow and Tooling

Polaris Reliability Agent coordinates specialists through deterministic tools and orchestration components. Available tools and components by agent:

Specialist routes and intents

Polaris Reliability Agent exposes one route per specialist agent. For specialist routes with an intent argument, the Reliability Agent should choose the narrowest intent that satisfies the user request; the specialist then manages the internal deterministic tools required for that intent.

Specialist	Intent	Description	Tool Calls (in sequence)
Master Data Agent	n/a	Search or list stored equipment so the user can find asset identifiers before deeper analysis.	EquipmentSearchTool
Defect Elimination Agent	overview	Run the full defect-elimination overview across reliability summary, equipment bad actors, repeat failures, failure-mode bad actors, and recommendations.	ReliabilityMetricsTool BadActorAnalysisTool RepeatFailureDetectionTool FailureModeBadActorAnalysisTool
Defect Elimination Agent	rank_bad_actors	Rank high-impact equipment using corrective-like work history, downtime, cost, MTTR, and MTBF context.	ReliabilityMetricsTool BadActorAnalysisTool
Defect Elimination Agent	find_repeat_failures	Find repeated equipment/failure-mode patterns that meet the occurrence threshold.	ReliabilityMetricsTool RepeatFailureDetectionTool
Defect Elimination Agent	rank_failure_mode_bad_actors	Rank repeated equipment/failure-mode patterns from repeat-failure findings by recurrence, downtime, and cost.	ReliabilityMetricsTool RepeatFailureDetectionTool FailureModeBadActorAnalysisTool
Maintenance Strategy Agent	full_strategy_review	Run the full maintenance strategy review from profile through recommendations.	MaintenanceStrategyProfileBuilderTool MaintenanceMixAnalyzerTool FailureModeCoverageAnalyzerTool FrequencyRiskAnalyzerTool MaintenanceStrategyGapDetectorTool MaintenanceStrategyRecommendationBuilderTool
Maintenance Strategy Agent	summarize_strategy_profile	Summarize existing maintenance strategy tasks, active task counts, types, frequencies, and statuses.	MaintenanceStrategyProfileBuilderTool
Maintenance Strategy Agent	maintenance_mix	Summarize preventive, inspection, condition-monitoring, corrective, and emergency work-order mix.	MaintenanceStrategyProfileBuilderTool MaintenanceMixAnalyzerTool
Maintenance Strategy Agent	check_coverage	Compare observed failure modes with active strategy task descriptions to classify coverage.	MaintenanceStrategyProfileBuilderTool MaintenanceMixAnalyzerTool FailureModeCoverageAnalyzerTool
Maintenance Strategy Agent	assess_frequency	Compare task intervals with observed repeat-failure recurrence to flag engineering-review risks.	MaintenanceStrategyProfileBuilderTool MaintenanceMixAnalyzerTool FailureModeCoverageAnalyzerTool FrequencyRiskAnalyzerTool
Maintenance Strategy Agent	detect_gaps	Identify missing active strategies, uncovered failure modes, and recurring partial-coverage gaps.	MaintenanceStrategyProfileBuilderTool MaintenanceMixAnalyzerTool FailureModeCoverageAnalyzerTool FrequencyRiskAnalyzerTool MaintenanceStrategyGapDetectorTool

Reliability Agent orchestration components

• ReliabilityAgentOrchestrator runs the bounded Reliability Agent loop: selects specialist routes, executes validated calls, suppresses duplicate calls with the same arguments, consolidates evidence, and returns the final response.
  • Final synthesis consolidates specialist evidence, applies synthesis guidance, optionally uses roadmap sequencing, and writes the user-facing answer.
  • Answer quality loop reviews and revises the draft answer through persisted model call phases: agent_tool_selection, agent_roadmap_planning, agent_final_synthesis, answer_review, answer_revision, and answer_revision_final.
  • Roadmap sequencing helper uses ROADMAP_PLANNER_TOOL_DEFINITION as an optional final-synthesis tool definition, not a registered specialist capability. It is used only after specialist evidence has identified recommendations or opportunities that need now, next, and later sequencing.
  • Recommendation decision guidance uses RECOMMENDATION_DECISION_MATRIX as synthesis guidance, not a tool. It helps decide whether recommendations from Defect Elimination and Maintenance Strategy should become a formal investigation or a maintenance strategy improvement.
• SpecialistRegistry exposes the active top-level callable specialist capabilities to the Reliability Agent: search_equipment_master, analyze_defect_elimination, and review_maintenance_strategy. Each specialist then runs its own internal deterministic tools for the selected intent.
• ToolCallCollector records specialist sub-tool progress and streams review, specialist, deterministic-tool, synthesis, and answer quality stages to the chat UI.
• ContextBuilder builds bounded chat context from the Reliability Agent system prompt, durable memory, recent history, and the latest user request.
• MemoryService updates and compacts conversation memory for follow-up questions.

Master Data Agent tools

• EquipmentSearchTool — searches stored equipment by text and asset filters, returning paginated equipment records plus status and equipment-type counts.

Defect Elimination Agent tools

• ReliabilityMetricsTool — summarizes work-order volume, activity mix, cost, downtime, date range, and corrective-to-preventive ratio.
• BadActorAnalysisTool — ranks high-impact equipment using corrective events, downtime, cost, MTTR, and MTBF context.
• RepeatFailureDetectionTool — finds recurring equipment and failure-mode patterns from linked work orders.
• FailureModeBadActorAnalysisTool — ranks repeated equipment/failure-mode patterns from RepeatFailureDetectionTool output by recurrence, downtime, and cost.

Recommendation synthesis for Defect Elimination is implemented inside DefectEliminationAgent rather than as a separate tool class.

Maintenance Strategy Agent tools

• MaintenanceStrategyProfileBuilderTool — summarizes existing maintenance strategy tasks, active task count, task types, and frequency details.
• MaintenanceMixAnalyzerTool — summarizes executed work-order history by preventive, inspection, condition-monitoring, corrective, and emergency work; calculates the reactive-to-planned maintenance ratio; and totals cost and downtime so strategy reviews can compare the planned strategy against actual maintenance demand.
• FailureModeCoverageAnalyzerTool — compares observed failure modes with active strategy task descriptions to classify coverage.
• FrequencyRiskAnalyzerTool — compares task intervals with observed repeat failure recurrence to flag weak intervals for review.
• MaintenanceStrategyGapDetectorTool — identifies missing active strategies, uncovered failure modes, and partial coverage gaps.
• MaintenanceStrategyRecommendationBuilderTool — returns bounded keep, modify, add, and engineering_review recommendations from the evidence produced by the preceding tools, including condition-monitoring suggestions when observed failure modes have a suitable monitoring method.

Future Reliability Improvement Agent tools

The Reliability Improvement Agent is intentionally disabled from the active Reliability Agent specialist registry for now. Its implementation remains in the codebase for future development, including ValueEstimatorTool, ActionPlanBuilderTool, OutcomeReporterTool, and RoadmapPlannerTool. RoadmapPlannerTool may still be used as a narrow Reliability Agent final synthesis helper when already-identified opportunities need now, next, and later sequencing.

Memory Architecture

Conversation memory is a durable Markdown summary stored on each conversation, separate from the full message history. It preserves long-lived reliability context such as objectives, equipment identifiers, known facts, assumptions, decisions, recommended actions, and open questions.

On each chat turn, ConversationChatService loads the conversation, previous messages, and current memory_markdown. ContextBuilder injects the memory as a system message alongside the Reliability Agent system prompt, the latest bounded conversation history, and the current user request. This keeps recent dialogue available while giving durable facts a predictable place in the model context.

Memory is token-budgeted separately from chat history. The current implementation reserves up to one tenth of the provider context window for memory, one quarter for the response, and a small safety margin. If the memory exceeds its budget, MemoryService compacts it before the response is generated.

After the assistant response is saved, MemoryService updates the Markdown memory from the previous memory, latest user message, and latest assistant response. Updates use fixed headings to keep confirmed facts, assumptions, decisions, recommended actions, and open questions distinct. Each saved memory state is also recorded as a ConversationMemoryRevision with the message sequence number it covers.

Memory is concise and durable rather than a full transcript. Detailed history remains in persisted messages, while memory carries forward the stable context needed for follow-up reliability analysis.

Apps

• apps/web — Next.js frontend for Polaris.
• apps/api — FastAPI backend for conversations, message persistence, memory updates, and model-provider access.

Local setup

Postgres

The local database runs through Docker Compose using the postgres service in docker-compose.yml. It uses the pgvector/pgvector:pg17 image and persists data in the postgres_data Docker volume.

Start Postgres from the repository root:

docker compose up -d postgres

The local database connection details are:

Host: 127.0.0.1
Port: 5432
Database: open_reliability
User: open_reliability
Password: open_reliability

Use this API DATABASE_URL for the Docker Compose database:

DATABASE_URL=postgresql+psycopg://open_reliability:open_reliability@127.0.0.1:5432/open_reliability

To stop the local database without deleting data:

docker compose stop postgres

To remove the local database data and start fresh:

docker compose down -v

API

cd apps/api
cp .env.example .env
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
./.venv/bin/alembic upgrade head
./.venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Update apps/api/.env:

OPENROUTER_API_KEY=sk-or-v1-your-key
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_SITE_URL=http://localhost:3000
OPENROUTER_APP_NAME=Polaris
FRONTEND_URL=http://localhost:3000

DATABASE_URL=postgresql+psycopg://open_reliability:open_reliability@127.0.0.1:5432/open_reliability

The OpenRouter key is used only by the backend. Never place it in apps/web/.env.local, expose it through a NEXT_PUBLIC_* variable, or commit the real key to Git.

Restart or reload Uvicorn after changing apps/api/.env, because environment settings are loaded when the backend starts.

Web

cd apps/web
npm install
npm run dev

The frontend expects:

NEXT_PUBLIC_API_URL=http://localhost:8000

Open Polaris at:

http://localhost:3000/ask-polaris

The homepage is available at both / and /polaris.

Useful checks

API:

cd apps/api
./.venv/bin/python -m pytest
./.venv/bin/python -m compileall app tests

Web:

cd apps/web
npm run lint
npm run build

Notes for contributors

• Keep feature work incremental.
• Preserve existing user changes in the working tree.
• Do not commit real secrets from .env files.

License

Polaris is licensed under the Apache License 2.0. See NOTICE for attribution information.