Merge pull request #932 from jupyter-naas/931-documentation-update

docs(README): update production deployment section and get started

Author: jravenel

README.md

@@ -2,224 +2,121 @@
 <img src="libs/naas-abi/naas_abi/apps/nexus/apps/web/public/abi-logo-rounded.png" alt="ABI Logo" width="128" height="128">
 
 # ABI
-*Agentic Brain Infrastructure*
+
+_Question Everything, Create your own AI System_
+
+ABI (Agentic Brain Infrastructure) is the open-source AI Operating System that grounds LLMs in your organization's ontology to create tools that extend human capabilities. An open and accessible alternative to Palantir.
+
 </div>
 
 <div align="center">
 
 [![Version](https://img.shields.io/badge/version-ABI--OS1%20Beta-red.svg)](https://github.com/jupyter-naas/abi/releases)
-[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-00a393.svg)](https://fastapi.tiangolo.com/)
 
-
 [![GitHub Stars](https://img.shields.io/github/stars/jupyter-naas/abi?style=social)](https://github.com/jupyter-naas/abi/stargazers)
 [![GitHub Forks](https://img.shields.io/github/forks/jupyter-naas/abi?style=social)](https://github.com/jupyter-naas/abi/network/members)
 [![Contributors](https://img.shields.io/github/contributors/jupyter-naas/abi.svg)](https://github.com/jupyter-naas/abi/graphs/contributors)
 
 </div>
 
-> Multi-agent AI Operating System with semantic knowledge graphs, ontology-driven reasoning, and intelligent workflow automation.
-
-⭐ **Star and follow to stay updated!**
-
 ## Quick Start
 
 ### Prerequisites
-```bash
-# Install uv package manager
-curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# Install Docker Desktop (for local services)
-# https://www.docker.com/products/docker-desktop
-```
-
-### Local Development
-```bash
-# Clone repository
-git clone https://github.com/jupyter-naas/abi.git
-cd abi
 
-# Install dependencies (Python + frontend)
-uv sync --all-extras
+- Python 3.12+, Git, [uv](https://astral.sh/uv) (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+- [Docker Desktop](https://www.docker.com/products/docker-desktop) (8GB+ RAM for full stack)
+- LLMs API key: OpenAI and OpenRouter
 
-# Install frontend dependencies
-cd libs/naas-abi/naas_abi/apps/nexus/apps/web
-pnpm install
-cd ../../../../..
+You also need to have the `docker` command available in your terminal.
 
-# Create local config
-cp config.yaml.example config.yaml
-# Edit config.yaml with your API keys
-
-# Configure for local development (update .env)
-# Change Docker hostnames to localhost:
-#   POSTGRES_HOST=localhost (not postgres)
-#   QDRANT_HOST=localhost (not qdrant)
-#   MINIO_HOST=localhost (not minio)
+### Local Development
 
-# Start infrastructure
-docker compose up -d postgres fuseki rabbitmq
+```bash
+uv tool install naas-abi-cli --force --upgrade
 
-# Start platform
-uv run abi stack start
+abi new project demo #You can change the project name to your own
+cd demo
+abi start
 ```
 
-**Platform will launch at:**
-- 🌐 **Nexus UI**: http://localhost:3000
-- 📊 **Nexus API**: http://localhost:9879
-- 🤖 **Agent API**: http://localhost:8001
-- 🗄️ **Fuseki**: http://localhost:3030
+**Platform launch:**
+
+- Services Portal: https://localhost:8080
+- Backend: https://api.localhost (Important: you must access it first and accept the self-signed TLS certificate for the frontend to work)
+- Frontend: https://nexus.localhost
 
 ### CLI Commands
+
 ```bash
-uv run abi stack start         # Start all services
-uv run abi stack stop          # Stop all services
-uv run abi stack status        # Show service health
-uv run abi stack logs [svc]    # Stream BFO logs (api|web|core|all)
-uv run abi seed-jena           # Populate graph database
-uv run abi chat                # Interactive agent chat
+abi start         # Start all services
+abi stop          # Stop all services
+abi chat          # Interactive agent chat
+abi config validate # Validate the configuration
 ```
 
-### Configuration
-
-**Minimal config (loads AbiAgent only):**
-```yaml
-modules:
-  - module: naas_abi
-    enabled: true
-  - module: naas_abi_core.modules.templatablesparqlquery
-    enabled: true
-  - module: naas_abi_marketplace.ai.chatgpt
-    enabled: true
-
-services:
-  triple_store:
-    triple_store_adapter:
-      adapter: "apache_jena_tdb2"
-      config:
-        jena_tdb2_url: "http://admin:abi@localhost:3030/ds"
-```
+## How It Works
 
-## Architecture
-
-**Four-Layer AI Operating System:**
-
-1. **User Layer**: Chat UI, REST API, MCP Protocol
-2. **Agent Layer**: ABI SuperAssistant + 20+ domain experts
-3. **Storage Layer**: Knowledge Graph (Jena/Oxigraph), Vector DB (Qdrant), Memory (PostgreSQL)
-4. **Execution Layer**: Ontologies (BFO), Workflows, Integrations, Analytics
-
-```mermaid
-graph LR
-    USER[👤 User] --> APPS[📱 Apps]
-    APPS --> AGENTS[🧠 Agents]
-    AGENTS --> STORAGE[(💾 Storage)]
-    AGENTS --> EXEC[⚙️ Components]
-    STORAGE --> KG[(Knowledge Graph)]
-    STORAGE --> VDB[(Vector DB)]
-    EXEC --> ONT[Ontologies]
-    EXEC --> WF[Workflows]
-```
+**1. Your data becomes structured knowledge**
 
-## Key Features
+Connect any data source: CRMs, code repositories, databases, productivity tools, financial systems. ABI ingests everything, maps relationships between entities, and builds a living knowledge graph of your organization. Not a data warehouse. A model of your reality.
 
-### 🤖 Multi-Model AI
-- **Cloud**: ChatGPT, Claude, Gemini, Grok, Llama, Mistral
-- **Local**: Qwen, DeepSeek, Gemma (via Ollama)
-- **Supervisor**: ABI agent with intelligent routing
+**2. Your team gets AI that knows their job**
 
-### 🧠 Knowledge Management
-- **Semantic Graph**: BFO-compliant RDF ontologies
-- **SPARQL Queries**: 30+ optimized queries
-- **Vector Search**: Intent matching via embeddings
-- **Memory**: Persistent conversation context
+Build agents for any role and workflow, each grounded in your organization's ontology. They understand the context of the work, not just the words in the question. The more you build, the deeper the institutional intelligence.
 
-### 🏪 Marketplace
-- **Domain Experts**: 20+ agents (Engineer, Analyst, Creator, etc.)
-- **Integrations**: GitHub, LinkedIn, Google, PostgreSQL, ArXiv, etc.
-- **Modular**: Enable/disable via `config.yaml`
+**3. Every question finds the right intelligence**
 
-### ⚙️ Automation
-- **Workflows**: End-to-end process automation
-- **Pipelines**: Data → Semantic transformation
-- **Event-Driven**: Knowledge graph triggers
-- **Integrations**: External APIs and exports
+A supervisor agent reads the intent behind each request and routes it to the right AI model, domain expert agent, or directly into your knowledge graph. Swap providers without rebuilding. The infrastructure adapts as AI evolves.
 
-### 🌐 Multiple Interfaces
-- **Terminal**: `uv run abi chat` - Interactive CLI
-- **REST API**: HTTP endpoints
-- **MCP Protocol**: Claude Desktop / VS Code
-- **Web UI**: http://localhost:3000
+For the full architecture, including module structure, five-layer stack, services, and data flow, see [The ABI Stack](https://docs.naas.ai/architecture/the-stack).
 
-### Production Deployment
+## Repository Layout
 
-### Deploy to Naas Cloud
-```bash
-uv run abi deploy naas
-```
-Requires [Naas subscription](https://naas.ai). Deploys as containerized API at `https://{space}.default.space.naas.ai`
+| Package                | What it does                                                     |
+| ---------------------- | ---------------------------------------------------------------- |
+| `naas-abi-core`        | Infrastructure adapters: storage, vector DB, message bus, SPARQL |
+| `naas-abi`             | Core agents, ontologies, and the Nexus app (API + web UI)        |
+| `naas-abi-cli`         | The `abi` CLI                                                    |
+| `naas-abi-marketplace` | Optional domain agents and third-party integrations              |
+
+## Production Deployment
 
 ### Self-Hosted Docker
+
 ```bash
-docker-compose up -d
+docker compose up -d
 ```
+
 Full stack with PostgreSQL, Fuseki, Qdrant, MinIO
 
-## Services
+### Managed Hosting
 
-| Service | Port | Purpose |
-|---------|------|---------|
-| Nexus Web | 3000 | Frontend UI |
-| Nexus API | 9879 | Platform API |
-| Agent API | 8001 | Agent execution |
-| Fuseki | 3030 | Graph database |
-| PostgreSQL | 5432 | Relational DB |
-| Qdrant | 6333 | Vector DB |
-| MinIO | 9000/9001 | Object storage |
+Need a hosted, managed deployment? [Get started on naas.ai](https://naas.ai) or reach out to the team directly.
 
 ## Why ABI?
 
-**Ontology-Based AI for Freedom to Reason**: When semantic alignment meets kinetic action through ontology-driven systems, we get one of the most powerful technologies ever created. This power should be distributed, not concentrated - the ability to understand, reason, and act upon complex information is fundamental to human autonomy and democratic society.
+Most AI tools are black boxes. ABI is built on open standards so every decision is traceable, every model is replaceable, and you own your data.
+
+**Built on international standards:**
 
-**Built on International Standards:**
 - [ISO/IEC 42001:2023](https://www.iso.org/standard/42001) - AI Management Systems
 - [ISO/IEC 21838-2:2021](https://www.iso.org/standard/74572.html) - Basic Formal Ontology (BFO)
 - EU AI Act compliance-ready
 
-**For:**
-- 👤 **Individuals**: Run locally, own your data
-- ⚡ **Pro**: Automate workflows, optimize costs
-- 👥 **Teams**: Share knowledge, build agents
-- 🏢 **Enterprise**: Deploy at scale, full control
-
 ## Research & Development
 
 Collaborative effort between:
+
 - **[NaasAI](https://naas.ai)** - Applied AI Research Lab
 - **[OpenTeams](https://openteams.com/)** - Open SaaS Infrastructure
 - **[University at Buffalo](https://www.buffalo.edu/)** - Research University
 - **[NCOR](https://ncor.buffalo.edu/)** - National Center for Ontological Research
 - **[Forvis Mazars](https://www.forvismazars.com/)** - Global Audit & Consulting
 
-## Requirements
-
-**System:**
-- Python 3.10+
-- uv package manager
-- Git
-
-**Hardware (Minimal - Cloud AI):**
-- 2GB+ RAM
-- 500MB disk
-
-**Hardware (Full - Local/Docker):**
-- 8GB+ RAM
-- 10GB+ disk
-- Docker Desktop
-
-**API Keys (at least one):**
-- OpenAI, Anthropic, Google AI, OpenRouter, or other LLM providers
+⭐ **If ABI is useful to you, star the repo to help others find it.**
 
 ## Contributing
 
@@ -229,4 +126,4 @@ We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guideline
 
 MIT License - see [LICENSE](https://opensource.org/licenses/MIT)
 
-For enterprise support: support@naas.ai
+For enterprise support or managed hosting, visit [naas.ai](https://naas.ai).