Skip to content

Application Stubs

Location: applications_stub/

Application stubs are production-ready starter scaffolds. They give teams a correct, consistent project structure from day one — so the first commit is business logic, not boilerplate.

Agentic Application Stub (agentic_application/)

Project structure

agentic_application/
├── api/          ← FastAPI routes and request/response models
├── cli/          ← Typer CLI entrypoints for local execution
├── agents/       ← Agent definitions (system prompt, model config, tools)
├── tools/        ← Tool registry and function implementations
├── core/         ← Shared runtime abstractions, error types, logging setup
└── config/       ← Pydantic Settings model, environment-driven configuration

What's included

Pydantic Settings model — all configuration comes from environment variables with type validation and defaults. No hardcoded values anywhere.

Tool registry — same TOOL_REGISTRY pattern used in MCP servers. Add a new tool by registering it; remove it by deleting the entry. No scattered imports.

CLI entrypoint — run the agent locally with python -m cli.run --query "..." before wiring up the API layer.

Prompt and skill scaffolding — placeholder system prompt, skill loader stubs, and a configurable model selection — ready to customise for your domain.

Baseline enterprise patterns:

  • Structured JSON logging via the core libs logger
  • Centralised error types for consistent API error responses
  • Runtime abstractions that isolate LLM provider details from agent code

Why teams use it

Problem What the stub provides
Every new project re-invents folder structure Pre-defined layered layout that matches the recipe conventions
Config scattered across files Single Pydantic Settings model — one place to look
Inconsistent error handling across services Shared error type hierarchy from core/
Slow onboarding for new engineers A working skeleton with clear entry points and comments

Getting started

# Copy the stub to your new project
cp -r applications_stub/agentic_application/ my_new_agent/
cd my_new_agent

# Set up environment
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Configure
cp config/sample.env .env
# Edit .env with your OCI credentials, LLM endpoint, DB config

# Run locally via CLI
python -m cli.run --query "Summarise the top 5 open invoices"

# Start the API
uvicorn api.main:app --reload --port 8000

UI Application Stub (ui_application/)

A React-based frontend scaffold that pairs with the agentic application backend. Both the invoice automation and smart dispatch UIs were built from this foundation.

Project structure

ui_application/
├── src/
│   ├── components/
│   │   ├── ChatInterface.tsx    ← Query input + streaming response display
│   │   ├── ResultCard.tsx       ← Structured agent output renderer
│   │   └── DashboardLayout.tsx ← Sidebar nav + header + content area
│   ├── hooks/
│   │   ├── useAgent.ts         ← API client hook for agent calls
│   │   └── useAuth.ts          ← IDCS SSO login/logout state
│   ├── api/
│   │   └── client.ts           ← Axios client with Bearer token injection
│   └── App.tsx                 ← Router + auth guard
├── .env.sample                 ← VITE_API_BASE_URL, VITE_IDCS_DOMAIN
└── vite.config.ts

What's included

IDCS SSO integration — useAuth.ts handles the redirect-based OIDC login flow and stores the access token for API calls. The auth guard in App.tsx blocks unauthenticated routes.

Chat interface — ChatInterface.tsx sends queries to the FastAPI backend and streams responses. Handles loading states, error display, and conversation history.

Structured result rendering — ResultCard.tsx renders tabular data, approval decision cards, and invoice summaries from structured JSON responses — the format the agentic application backend returns.

API client — client.ts injects the current IDCS bearer token into every request header. No manual token management in component code.

Getting started

cp -r applications_stub/ui_application/ my_agent_ui/
cd my_agent_ui
npm install

# Configure
cp .env.sample .env
# Set VITE_API_BASE_URL=http://localhost:8000 and VITE_IDCS_DOMAIN

npm run dev       # Development server on port 5173
npm run build     # Production bundle in dist/

When to use stubs vs recipes

Situation Use
Starting a brand-new domain solution agentic_application stub — clean slate with correct structure
Building something similar to invoice processing invoice_automation recipe — fork and adapt
Building a dispatch or routing workflow smart_dispatch recipe — fork and adapt
Need a React UI for your agent ui_application stub