Genai Services

OCI Generative AI Services - Expert Knowledge

🏗️ Use OCI Landing Zone Terraform Modules

Don't reinvent the wheel. Use oracle-terraform-modules/landing-zone for GenAI infrastructure.

Landing Zone solves:

• ❌ Bad Practice #1: Generic compartments (Landing Zone creates AI/ML workload compartments)
• ❌ Bad Practice #4: Poor segmentation (Landing Zone isolates GenAI endpoints in private subnets)
• ❌ Bad Practice #10: No monitoring (Landing Zone configures GenAI usage alarms)

This skill provides: GenAI cost optimization, rate limits, PHI/PII security, and troubleshooting for GenAI deployed WITHIN a Landing Zone.

---

⚠️ OCI CLI/API Knowledge Gap

You don't know OCI CLI commands or OCI API structure.

Your training data has limited and outdated knowledge of:

• OCI CLI syntax and parameters (updates monthly)
• OCI GenAI API endpoints and request/response formats
• GenAI service CLI operations (oci generative-ai)
• Available models, token limits, and pricing (changes frequently)
• Latest GenAI features (Agents, RAG) and API changes

When OCI operations are needed:

1. Use exact CLI commands from this skill's references
2. Do NOT guess OCI CLI syntax or parameters
3. Do NOT assume model availability or pricing
4. Load reference files for detailed GenAI API documentation

What you DO know:

• General LLM concepts and prompting patterns
• Token estimation and context management
• API integration patterns

This skill bridges the gap by providing current OCI GenAI-specific patterns and gotchas.

---

You are an OCI GenAI expert. This skill provides knowledge Claude lacks: cost optimization specifics, token management, rate limit handling, PHI/PII security, response validation, and model selection trade-offs.

NEVER Do This

❌ NEVER send PHI/PII identifiers to GenAI APIs (HIPAA/GDPR violation)

# WRONG - patient identifiers sent to external service
prompt = f"Transcribe note for patient {patient_name}, MRN {mrn}, SSN {ssn}: {note}"

# RIGHT - redact identifiers
prompt = f"Transcribe this medical note: {redacted_note}"
# Keep mapping: temp_id → real_id in secure database, not in prompts

Why critical: GenAI service logs may retain data, violates healthcare regulations

❌ NEVER trust GenAI output without validation (hallucination risk)

# WRONG - use response directly in critical systems
diagnosis = genai_response.text
db.execute("UPDATE patients SET diagnosis = ?", diagnosis)

# RIGHT - validate structure and flag for human review
response = genai_response.text
if validate_medical_format(response):
    db.execute("UPDATE patients SET ai_suggested_diagnosis = ?, status = 'PENDING_REVIEW'", response)

Hallucination rate: 5-15% for factual queries, higher for medical/legal domains

❌ NEVER ignore token limits

• command-r-plus: 128k context window (input + output)
• command-r: 4k context (much cheaper but limited)
• Exceeding limit: Request truncated silently or fails with 400 error

❌ NEVER call GenAI without rate limit handling

# WRONG - no retry logic, fails on rate limit
response = genai_client.chat(request)

# RIGHT - exponential backoff
def call_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except oci.exceptions.ServiceError as e:
            if e.status == 429 and attempt  tuple[bool, list[str]]:
    """Validate GenAI medical response for safety"""

    issues = []

    # Check 1: Response not empty
    if not response or len(response.strip())  tuple[str, dict]:
    """Remove PHI from text, return redacted text + mapping"""

    mapping = {}
    redacted = text

    # Patient names (use NER or pattern matching)
    names = extract_names(text)  # Your NER function
    for i, name in enumerate(names):
        placeholder = f"[PATIENT_{i}]"
        mapping[placeholder] = name
        redacted = redacted.replace(name, placeholder)

    # Medical Record Numbers
    mrn_pattern = r'\b(MRN|Medical Record):?\s*([A-Z0-9]{6,10})\b'
    redacted = re.sub(mrn_pattern, r'\1: [REDACTED]', redacted)

    # SSN
    ssn_pattern = r'\b\d{3}-\d{2}-\d{4}\b'
    redacted = re.sub(ssn_pattern, '[SSN_REDACTED]', redacted)

    # Dates (optional - some use cases need dates)
    # date_pattern = r'\b\d{1,2}/\d{1,2}/\d{4}\b'
    # redacted = re.sub(date_pattern, '[DATE]', redacted)

    return redacted, mapping

# Usage
redacted_note, phi_mapping = redact_phi(patient_note)
genai_response = genai_client.chat(prompt=f"Summarize: {redacted_note}")
# Store phi_mapping securely, use to re-identify if needed

Progressive Loading References

OCI Generative AI Reference (Official Oracle Documentation)

WHEN TO LOAD [oci-genai-reference.md](references/oci-genai-reference.md):

• Need comprehensive GenAI API documentation
• Understanding all available models and capabilities
• Implementing RAG (Retrieval-Augmented Generation) with OCI
• Need official Oracle guidance on GenAI Agents
• Understanding fine-tuning and custom model deployment

Do NOT load for:

• Quick API usage examples (covered in this skill)
• Model selection guidance (decision tree above)
• Cost calculations (formulas above)

---

When to Use This Skill

• GenAI API implementation: model selection, cost estimation, SDK usage
• Error troubleshooting: rate limits (429), token limits (400), authentication
• Cost optimization: caching strategy, model downgrade, prompt optimization
• Healthcare/compliance: PHI handling, HIPAA requirements, audit logging
• Response validation: hallucination detection, structure checking
• Production: rate limit handling, error recovery, monitoring

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: acedergren
• Source: acedergren/oci-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.