Getting Started¶

Project Inception is an agentic landing zone for OCI. This page walks you through the four deployment phases — from core setup to production recipes — and shows how to run the documentation site locally.

Prerequisites¶

Tool	Version	Purpose
Python	3.13+	All backend services and agents
Node.js	18+	React frontends (Smart Dispatch, Invoice Automation)
SQLcl	Latest	Oracle DB access via MCP SQLcl server
OCI CLI	Latest	OCI resource management and auth
Git	Latest	Clone the repository
Terraform	1.5+	Security infrastructure provisioning (optional)

OCI requirements: tenancy with admin access to ADB, IDCS, API Gateway, and Vault; an Oracle ADB wallet; an OCI API key in ~/.oci/config.

Phase 1 — Core Setup¶

1.1 Clone the repository¶

git clone https://github.com/aojah1/ent_ai_fabric_dev.git
cd ent_ai_fabric_dev

1.2 Install core libraries¶

The shared foundation — LLM factory, METRO observability, DB helpers, and the Token Factory auth library:

cd inception_core/libs
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

1.3 Configure Token Factory¶

TokenFactory translates IDCS tokens into Oracle DB tokens and OCI service signers. It is required by the MCP ADW server and the E2E identity propagation patterns.

Add to your module .env:

DOMAIN_URL="https://<domain>.identity.oraclecloud.com:443"
DOMAIN_OCI_REGION="us-chicago-1"
TOKEN_EXCHANGE_CREDS_OCID="ocid1.vaultsecret.oc1..<app-secret>"
TOKEN_FACTORY_ISSUER="https://upst.tokenfactory/"
TOKEN_FACTORY_PRIVATE_KEY_SECRET_OCID="ocid1.vaultsecret.oc1..<private-key>"
TOKEN_FACTORY_CERT_SECRET_OCID="ocid1.vaultsecret.oc1..<certificate>"
TOKEN_FACTORY_KID="token-factory-cert"
TOKEN_FACTORY_PROPAGATION_TRUST_CLAIM="upstclient:tokenexchange"

See Token Factory for the full configuration reference and OCI prerequisites.

1.4 Deploy IAM / IDCS¶

Follow the Business IAM App guide to create:

A confidential IDCS application for OAuth2 Authorization Code flow (for web UIs)
A token-factory confidential app with client_credentials + jwt-assertion grants
An IdentityPropagationTrust for UPST-backed DB token flows

1.5 Configure OCI API key (for non-interactive / CLI flows)¶

For agents, background jobs, and CLIs that cannot do browser OAuth, authentication uses OCI API key signing (RSA-SHA256 token exchange). Add to your agent .env:

OCI_IDENTITY_TOKEN_URL=https://<domain>.identity.oraclecloud.com/oauth2/v1/token
OCI_IDENTITY_TENANCY_OCID=ocid1.tenancy.oc1..<tenancy>
OCI_IDENTITY_USER_OCID=ocid1.user.oc1..<user>
OCI_IDENTITY_FINGERPRINT=xx:xx:xx:xx:..
OCI_IDENTITY_PRIVATE_KEY_FILE=~/.oci/oci_api_key.pem
OCI_IDENTITY_SCOPE=urn:opc:idm:__myscopes__

See Solution Patterns — Service Token Acquisition for the full pattern.

Phase 2 — MCP Servers¶

MCP servers expose Oracle data and OCI services as agent tools over HTTP. Deploy them before starting any recipe.

2.1 SQLcl MCP Server (`:3001`)¶

cd inception_mcp_servers/mcp_sqlcl
uv run python -m src.server_token

Verify:

curl http://127.0.0.1:3001/health

2.2 Object Storage MCP Server (`:3002`)¶

cd inception_mcp_servers/mcp_os
python -m src.server_token

2.3 ADW MCP Server (`:8003`)¶

cd inception_mcp_servers/mcp_adw
python -m src.server_token

2.4 (Optional) Vault setup¶

See Vault for storing MCP credentials and Token Factory keys as OCI Vault secrets.

Shared MCP .env keys:

IDCS_DOMAIN=<domain>.identity.oraclecloud.com
IDCS_CLIENT_ID=<client-id>
IDCS_CLIENT_SECRET=<client-secret>
SQLCL_PATH=/Applications/sqlcl/bin/sql
SQLCL_CONNECTION=<named-connection>

Phase 3 — Recipes¶

Recipes are complete, end-to-end applications. Each combines agents, MCP tools, memory, and a UI.

3.1 Smart Dispatch (recommended first run)¶

A multi-agent field service dispatch system. Requires MCP SQLcl (Phase 2.1) and an Oracle ADB wallet.

# 1. Python agents  (~30-60s first startup)
cd inception_recipes/smart_dispatch/smart_dispatch_agents
cp .env.example .env   # fill in ADB, IDCS, OCI GenAI, LangFuse values
uv run python -m src.api.dispatch_api

# 2. Node.js API gateway
cd inception_recipes/smart_dispatch/smart_dispatch_ui
npm install
cp .env.example .env   # fill in OCI_IDENTITY_* and IDCS OAuth values
node server/index.js

# 3. React UI (dev)
npm run dev
# → open http://localhost:8000 and log in via IDCS

Or use the CLI (no browser needed):

cd inception_recipes/smart_dispatch/smart_dispatch_agents
uv run python -m src.cli.smart_dispatch
# Logs in via OCI API key, connects to sidecaradb_high, then opens a REPL

See Smart Dispatch Architecture for full details.

3.2 Invoice Automation¶

cd inception_recipes/invoice_automation
python3.13 -m venv src/backend/venv3.13
source src/backend/venv3.13/bin/activate
pip install -r requirements.txt

nohup python src/backend/mcp_adw_server.py > src/backend/logs/mcp_server.log 2>&1 &
nohup python src/backend/fastapi_app.py     > src/backend/logs/fastapi.log 2>&1 &

npm install && npm run dev

3.3 Agent patterns and accelerators¶

The accelerators provide standalone, runnable building blocks:

cd inception_core/accelerators/patterns_agentic
source .venv/bin/activate
python -m src.agents.patterns.agent_with_augmented_llm
python -m src.agents.patterns.agent_with_routing

See Agentic Accelerators for all 7 patterns, memory patterns, and the deep research agent.

Phase 4 — DevOps¶

Productionize with containers and Terraform:

# Security infrastructure (IAM token exchange function, policies, network)
cd inception_devops/security/terraform-get-db-token-function
terraform init && terraform apply

# Build and push container images
cd inception_devops/containers
./build.sh mcp-sqlcl
./build.sh mcp-object-storage
./push.sh <region>.ocir.io/<tenancy>/<repo>

See Deployment for full OCI Container Instances, OKE, and API Gateway steps, and DevOps & Security for the complete DevOps guide.

Optional: configure the API Gateway to front MCP servers with IDCS OAuth enforcement and header token injection.

Environment configuration reference¶

Each module reads credentials from .env. Copy sample.env (where present) to .env.

Core / agents¶

# OCI identity
OCI_CONFIG_FILE=~/.oci/config
CONFIG_PROFILE=DEFAULT
OCI_REGION=us-chicago-1
OCI_COMPARTMENT_ID=ocid1.compartment.oc1...

# LLM
OCI_GENAI_ENDPOINT=https://inference.generativeai.us-chicago-1.oci.oraclecloud.com
OCI_GENAI_MODEL_ID=google.gemini-2.5-pro
OCI_EMBEDDING_MODEL=cohere.embed-v4.0

# Oracle ADB (memory, checkpointer)
ADB_USER=ADMIN
ADB_PASSWORD=<secret>
ADB_DSN=mydb_high
ADB_WALLET_LOCATION=./wallet
ADB_WALLET_PASSWORD=<secret>
TNS_ADMIN=./wallet

# IDCS (MCP auth — browser flows)
IDCS_DOMAIN=<domain>.identity.oraclecloud.com
IDCS_CLIENT_ID=<client-id>
IDCS_CLIENT_SECRET=<client-secret>

# OCI API key (non-interactive token exchange — CLI, gateway)
OCI_IDENTITY_TOKEN_URL=https://<domain>.identity.oraclecloud.com/oauth2/v1/token
OCI_IDENTITY_TENANCY_OCID=ocid1.tenancy.oc1..
OCI_IDENTITY_USER_OCID=ocid1.user.oc1..
OCI_IDENTITY_FINGERPRINT=xx:xx:xx:..
OCI_IDENTITY_PRIVATE_KEY_FILE=~/.oci/oci_api_key.pem
OCI_IDENTITY_SCOPE=urn:opc:idm:__myscopes__

# Observability
LANGFUSE_SECRET_KEY=sk-...
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_BASE_URL=https://langfuse.your-domain.com

Verify the setup¶

# Core library tests
cd inception_core/libs
pytest tests/ -v

# SQLcl MCP server health
curl http://127.0.0.1:3001/health

# Smart Dispatch CLI login probe
cd inception_recipes/smart_dispatch/smart_dispatch_agents
uv run python -m src.cli.smart_dispatch --help

# service_get_token unit tests
cd inception_core/accelerators/patterns_solution/service_get_token
pip install -e ".[dev]" -q && python -m pytest tests/ -v

Run the documentation site¶

pip install mkdocs mkdocs-material pymdown-extensions
mkdocs serve -a 127.0.0.1:8000   # hot-reloads on file save
mkdocs build                       # outputs to site/

Where to go next¶

Goal	Start here
Understand the platform layers	Architecture
Explore all 7 agent patterns	Agentic Accelerators
Deep-dive on auth and token flows	Solution Patterns
Smart Dispatch full architecture	Smart Dispatch
Token Factory configuration	Token Factory
MCP server details	MCP Servers
Production deployment to OCI	Deployment
Troubleshooting and validation	Troubleshooting · Validation