Skip to content

AI Core Libraries

Location: inception_core/libs/

The core libraries are the shared foundation every other module in the platform builds on. They provide consistent, tested primitives for LLM invocation, content governance, observability, and data access — so you never re-implement these from scratch in a recipe or application.

Package structure

inception_core/libs/src/
├── env.py                        ← Shared environment loader
├── auth/
│   └── token_factory/            ← Credential translation library (see Token Factory page)
│       ├── factory.py            ← TokenFactory.from_env() + get_token()
│       └── _factory_support.py   ← JWT assertion, UPST exchange, Vault reads
├── llm/
│   ├── llmfactory.py             ← Unified LLM provider abstraction
│   ├── image_analysis.py         ← Multimodal image processing
│   ├── pdf_processing.py         ← PDF extraction and chunking
│   └── video_analysis.py         ← Video frame analysis
├── metro/
│   ├── guardrails/
│   │   ├── oci_guardrails.py     ← OCI Guardrails integration
│   │   └── oci_guardrails_handler.py  ← LangChain-compatible handler
│   ├── auditing/                 ← LangFuse audit integration
│   ├── evals/                    ← AE-09 continuous-evaluation framework
│   │   ├── eval_factory.py       ← evalFactory().run_eval_suite() — the CI gate
│   │   ├── eval_models.py        ← EvalCase/Trace/ScorerResult Pydantic schema
│   │   ├── scorers.py            ← assertion / trajectory / groundedness / rubric layers
│   │   └── trace_capture.py      ← normalizes any target_fn's return into a Trace
│   └── logging/
│       ├── agentic_logging.py    ← Structured agent logging
│       └── oci_logginghandler.py ← OCI Logging sink handler
├── tools/
│   └── dus2_tool.py              ← OCI Document Understanding key/value extraction
└── utils/
    ├── db_conn_utils.py          ← Oracle ADB connection helpers
    └── upload_research_dataset.py ← Dataset ingestion utility

Token Factory

The auth/token_factory module is documented on its own page: Token Factory. It translates incoming IDCS tokens into Oracle DB tokens, OCI service signers, or OAuth access tokens — used by the MCP servers and E2E identity propagation patterns.

LLM Factory (llm/llmfactory.py)

The LLM factory is the single abstraction layer across all supported model providers. It lets you swap models without changing agent code.

Supported providers:

  • OCI GenAI (Cohere, Meta LLaMA, and other OCI-hosted models)
  • OpenAI-compatible endpoints (includes OCI GenAI via OpenAI SDK adapter)
  • Any provider that conforms to the LangChain chat model interface

Why it matters: Agents and recipes import the factory, not a provider directly. When your team switches from one model to another — for cost, capability, or compliance reasons — you change one config value, not every agent file.

Usage:

from src.llm.llmfactory import LLMFactory

# Returns a LangChain-compatible chat model
llm = LLMFactory.get_chat_model()

# Use directly in a LangGraph node
response = llm.invoke([HumanMessage(content="Summarise this invoice")])

# Or bind tools before passing to LangGraph
llm_with_tools = llm.bind_tools([execute_sql, upload_file])

Configuration:

OCI_GENAI_ENDPOINT=https://inference.generativeai.us-chicago-1.oci.oraclecloud.com
OCI_GENAI_MODEL_ID=cohere.command-r-plus
OCI_EMBEDDING_MODEL=cohere.embed-english-v3.0
OCI_COMPARTMENT_ID=ocid1.compartment.oc1...<your-compartment>

Multimodal Utilities (llm/)

Image Analysis (image_analysis.py)

Wraps OCI GenAI vision-capable models for image understanding tasks. Useful for document classification, receipt scanning, diagram parsing, and invoice image extraction.

from src.llm.image_analysis import analyze_image

result = analyze_image(
    image_path="invoice_scan.png",
    prompt="Extract vendor name, invoice date, and total amount"
)
# Returns structured dict with extracted fields

PDF Processing (pdf_processing.py)

Provides document extraction and chunking utilities for PDFs. Designed for RAG pipelines, knowledge base ingestion, and document-grounded agent tools.

from src.llm.pdf_processing import extract_pdf_chunks

chunks = extract_pdf_chunks("contract.pdf", chunk_size=512, overlap=64)
# Returns list of text chunks ready for embedding and vector storage

Video Analysis (video_analysis.py)

Frame-level analysis utilities for video content. Applicable to field service recording analysis, training data workflows, and multimedia content classification.

from src.llm.video_analysis import analyze_video_frames

summary = analyze_video_frames(
    video_path="field_recording.mp4",
    sample_rate=5,  # analyze every 5th frame
    prompt="Describe what the technician is doing"
)

Document Understanding (tools/dus2_tool.py)

An @tool-decorated function wrapping the OCI Document Understanding key/value extraction service (oci.ai_document). Call it directly as a deterministic pipeline step — never through a model tool-call loop — so extraction always runs rather than becoming something a model can skip or narrate instead of calling.

from tools.dus2_tool import extract_key_value

raw = extract_key_value("invoice_scan.pdf")  # submits + waits on the DU processor job

Configuration: COMPARTMENT_OCID, NAMESPACE_NAME, INPUT_BUCKET, SDK_RESULTS_STORAGE_BUCKET — see the module's own README.md for the full list.

The raw output is word-level OCR, not key-value pairs

DocumentKeyValueExtractionFeature() called with no custom model returns pages[].words[].text — full-page OCR with per-word bounding-polygon JSON, which can run 25-30k+ characters for a single-page document. Feed a collapsed plain-text transcript, not the raw JSON, to any normalization step, and don't truncate before the line-items/totals section — they typically appear later on the page than the header fields.

Governance Library (metro/)

The metro package groups all compliance, safety, and observability primitives under one roof.

OCI Guardrails (guardrails/oci_guardrails.py)

Wraps the OCI Generative AI Guardrails service to enforce:

  • Content safety — detect and block harmful content in agent inputs and outputs
  • Topic filtering — restrict agents to approved subject domains
  • Policy enforcement — apply custom content policies without writing prompt-level rules

Usage pattern:

from metro.guardrails.oci_guardrails import OCIGuardrails

guardrails = OCIGuardrails(config)
result = guardrails.check(user_input)
if result.blocked:
    return result.reason

Guardrails Handler (guardrails/oci_guardrails_handler.py)

A LangChain-compatible callback handler that integrates guardrail checks into the agent execution loop automatically. Drop it into any LangGraph or LangChain agent with zero changes to tool or prompt code.

Auditing (auditing/)

LangFuse integration hooks that emit structured trace events for every agent step:

  • Prompts sent and received
  • Tool calls and results
  • Token usage per step
  • Latency and error signals

These traces are queryable in the LangFuse dashboard for debugging, cost analysis, and quality evaluation.

Continuous Evaluation (evals/)

Implements AE-09 — Evaluate continuously (see Agentic Engineering): a hybrid trajectory-plus-outcome scoring framework that catches the failure class a single "does this reply look reasonable?" judge structurally cannot see — an agent that has a tool available, never calls it, and answers with a plausible-but-fabricated fact anyway. Four layers, cheapest and most reliable first:

Layer Question it answers Cost Catches
assertion Did the run end in the correct state? Free, zero-flake Wrong outcomes
trajectory Did the agent take the right steps? Free, zero-flake Routing/handoff bugs, a skipped tool call
groundedness Is every factual claim traceable to an actual tool result this turn? One narrow LLM call Fabrication despite tool access
rubric Qualitative dimensions that can't be asserted (tone, scope, policy citation) One LLM call, structured per-criterion verdict Subjective quality regressions

Cases are grouped into golden / edge / adversarial / regression categories, each with its own pass-rate threshold (configurable via .env). run_eval_suite(target_fn, cases_path, strict=True) raises on a missed threshold, so it drops straight into a pytest test or a CI step with no extra wiring:

from metro.evals.eval_factory import evalFactory

def target_fn(input_text: str, **context) -> dict:
    return my_compiled_graph.invoke({"messages": [HumanMessage(content=input_text)]})

result = evalFactory().run_eval_suite(target_fn, "tests/evals/cases/matching_rules.yaml")

Case files are versioned YAML — see Meridian Bank and EBS Invoice Reconciliation for two recipes with a live tests/evals/ suite wired to this module, including permanent category: regression cases reproducing real bugs found and fixed during development.

Known limitation, documented not hidden

The groundedness/rubric layers make a real LLM-judge call and can occasionally produce a different verdict on an identical input run-to-run, even at temperature=0. assertion/trajectory are pure Python and don't have this problem. Treat a lone groundedness/rubric failure as worth a re-run before calling it a real regression.

Structured Logging (logging/)

agentic_logging.py — Provides a structured JSON logger pre-configured for agentic workloads. Fields include agent ID, session thread, tool name, and execution stage.

oci_logginghandler.py — A Python logging.Handler subclass that ships logs to OCI Logging. Supports alerting rules, retention policies, and dashboards via OCI Log Analytics.

Utility Helpers (utils/)

Database Connection Utils (db_conn_utils.py)

Oracle ADB (Autonomous Database) connection helpers supporting:

  • Wallet-based mTLS connections
  • IAM token-based authentication
  • Connection pooling and lifecycle management

Used by checkpointer patterns, memory store backends, and MCP ADW tools.

Dataset Upload (upload_research_dataset.py)

Utility for ingesting research datasets into OCI Object Storage or Oracle ADB. Supports chunking, embedding generation, and vector store population — the setup step for RAG-capable agents.

Installation

The library is installed as a local editable package:

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

Testing

cd inception_core/libs
export PYTHONPATH=src
pytest tests/

What is covered:

Test area What is verified
Guardrails Blocked content returns a reason; approved content passes through cleanly
LLM invocation LLM factory returns a callable model; invoke returns a non-empty response
OCI Logging handler Log records are serialized and sent without error; log level filtering works
DB connection utils Wallet-based connection succeeds; connection pool lifecycle is clean
PDF processing Extracted text matches known fixture; chunk boundaries are correct

Run a specific test file to isolate failures:

pytest tests/test_guardrails.py -v
pytest tests/test_llmfactory.py -v