BeeAI Context Engineering

Companion code for the IBM Developer article:
"Build a Context-Aware AI Agent using the IBM BeeAI Framework"

📖 Read the full article on IBM Developer (link will be updated upon publication)

Overview

This repository demonstrates a production-ready implementation of context engineering patterns using the IBM BeeAI Framework. The code implements an 8-stage context pipeline with a 7-layer composition model for building context-aware AI agents that maintain memory, personalization, and dynamic knowledge retrieval across sessions.

What is Context Engineering?

Context engineering is the systematic practice of designing, managing, and optimizing the flow of contextual information throughout an AI agent's lifecycle—from initial collection and storage, through retrieval and transformation, to validation and injection into the model.

Where prompt engineering is stateless, context engineering is stateful, giving agents memory across time, channels, and users.

For a detailed explanation of the concepts, architecture, and banking analogy that illustrates these patterns, please refer to the companion IBM Developer article.

Features

• ✅ 8-Stage Context Pipeline: Collection → Storage → Retrieval → Transformation → Validation → Assembly → Injection → Monitoring
• ✅ 7-Layer Context Model: Foundation, Personalization, Continuity, Knowledge, Workflow, Action, Trigger
• ✅ Dynamic Knowledge Retrieval: Agent-callable tools for on-demand domain knowledge access
• ✅ IBM watsonx.ai Integration: Uses Granite models via watsonx.ai
• ✅ Production-Ready Patterns: Demonstrates real-world context management strategies
• ✅ Educational Code: Extensively commented with architectural explanations

Architecture

The implementation demonstrates:

1. Simulated Context Stores representing production storage tiers (PostgreSQL, Redis, Vector DB)
2. ProductKnowledgeTool for dynamic, agent-driven knowledge retrieval
3. Context Pipeline executing stages 3-7 of the architecture
4. Agent Invocation with proper memory injection and recency weighting

┌─────────────────────────────────────────────────────────────┐
│                    CONTEXT PIPELINE                          │
├─────────────────────────────────────────────────────────────┤
│ 1. Collection   → Gather from user input, system state      │
│ 2. Storage      → Hot/Warm/Cold/Vector tiers                │
│ 3. Retrieval    → Direct lookup, semantic search            │
│ 4. Transformation → Summarization, enrichment, filtering    │
│ 5. Validation   → Quality scoring, privacy enforcement      │
│ 6. Assembly     → Layer ordering, template application      │
│ 7. Injection    → System/user message split                 │
│ 8. Monitoring   → Latency, quality, resource metrics        │
└─────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

• Python 3.13 or higher
• IBM watsonx.ai account with API credentials (Sign up here)
• pip package manager

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/beeai-context-engineering.git
   cd beeai-context-engineering

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment variables:

   cp .env.example .env

   Edit .env with your watsonx.ai credentials:

   WATSONX_API_KEY=your_api_key_here
   WATSONX_URL=https://us-south.ml.cloud.ibm.com
   WATSONX_PROJECT_ID=your_project_id_here

5. Verify the model ID:

   Check the IBM watsonx.ai model catalog to ensure ibm/granite-3-8b-instruct is the current model identifier. Model IDs are updated with each release.

6. Run the application:

   python app.py

Expected Output

The application demonstrates two scenarios with different customer profiles:

=====================================================
   IBM BEEAI AGENTIC CONTEXT ENGINE — PART 1
=====================================================

>>> SCENARIO 1: Customer 001 — Conservative Parent
--- [INITIALIZING PIPELINE FOR cust_001] ---
User Query: Where should I invest this ₹5 lakhs for my daughter?
[Pipeline Log] Interaction for cust_001 complete.

🤖 AGENT RESPONSE:
Given your conservative risk profile and your daughter's upcoming college 
admission, I recommend the Education Savings Plan with Section 80C tax 
benefits, complemented by Secure Bonds for capital preservation...

>>> SCENARIO 2: Customer 002 — Aggressive Entrepreneur
--- [INITIALIZING PIPELINE FOR cust_002] ---
User Query: What are the best options for ₹2 lakhs cash right now?
[Pipeline Log] Interaction for cust_002 complete.

🤖 AGENT RESPONSE:
Given your aggressive risk tolerance and history with crypto and high-yield 
tech assets, I would look at the high-risk digital asset framework and 
aggressive tech mutual funds...

Key Observation: Two entirely different recommendations emerge from the same application logic, driven entirely by the context pipeline—not by different prompts or models.

Project Structure

beeai-context-engineering/
├── src/                      # Source code
│   ├── __init__.py           # Package initialization
│   └── app.py                # Main application with context pipeline
├── docs/                     # Extended documentation
│   ├── architecture.md       # Pipeline architecture deep dive
│   └── context-layers.md     # 7-layer model explanation
├── examples/                 # Usage examples
│   └── basic_usage.py        # Minimal example
├── .env.example              # Environment variables template
├── .gitignore                # Git ignore rules
├── CHANGELOG.md              # Version history
├── CONTRIBUTING.md           # Contribution guidelines
├── LICENSE                   # Apache License 2.0
├── README.md                 # This file
├── requirements.txt          # Python dependencies
└── requirements-dev.txt      # Development dependencies

Usage Examples

Basic Usage

from app import invoke_beeai_agent

# Invoke agent with customer context
response = await invoke_beeai_agent(
    customer_id="cust_001",
    user_query="Where should I invest for retirement?"
)
print(response)

Creating Custom Tools

See examples/custom_tools.py for how to create your own BeeAI tools for domain-specific knowledge retrieval.

Production Deployment

See docs/deployment.md for guidance on:

• Database configuration (PostgreSQL, Redis, Pinecone)
• Security best practices
• Monitoring and observability
• Scaling strategies

Documentation

• Architecture Guide: Deep dive into the 8-stage pipeline
• Context Layers: Detailed explanation of the 7-layer model
• Deployment Guide: Production deployment instructions
• API Reference: Code API documentation

Key Concepts

Context Pipeline Stages

Stage	Purpose
Collection	Gather from user input, system state, external feeds
Storage	Hot (in-memory), Warm (cache), Cold (DB), Vector (embeddings)
Retrieval	Direct lookup, semantic search, hybrid search
Transformation	Summarization, enrichment, filtering, prioritization
Validation	Quality scoring, privacy enforcement, token budget check
Assembly	Layer ordering, template application, optimization
Injection	System/user message split, direct prompt injection
Monitoring	Latency, quality, resource, and business metrics

Context Composition Layers

Layer	Purpose	Storage	TTL
Foundation	System message, role, capabilities	Config/App memory	Permanent
Personalization	User profile, preferences	PostgreSQL/Redis	1 hour
Continuity	Conversation history	Redis/In-memory	30-60 min
Knowledge	RAG results from documents	Vector DB/Redis	5-15 min
Workflow	Multi-step task state	Redis/In-memory	1 hour
Action	Recent tool call results	Ephemeral/Redis	1-5 min
Trigger	Current user query	Request object	Ephemeral

Best Practices

Concept	Failure Mode	Solution
Scope	Context bloat from irrelevant data	Filter aggressively; feed only task-relevant signals
Freshness	Stale data producing outdated recommendations	Time-weight context; define shelf-life for records
Granularity	Storing every interaction verbatim	Keep recent events verbatim; compress older ones
Conflict Resolution	Old profile contradicting live session	Session corrections always override historical data
Privacy	Cross-user data leakage	RBAC on retrieval; strict tenant isolation
Portability	Users repeating themselves across channels	Standardize context payloads across web/mobile/voice

Development

Running Tests

pip install -r requirements-dev.txt
pytest tests/

Code Quality

# Format code
black src/

# Lint code
ruff check src/

# Type checking
mypy src/

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• IBM BeeAI Framework: The agentic framework powering this implementation
• IBM watsonx.ai: Foundation model platform
• IBM Developer: For publishing the companion article

Citation

If you use this code in your research or project, please cite:

@article{padekar2024context,
  title={Build a Context-Aware AI Agent using the IBM BeeAI Framework},
  author={Padekar, Shailesh},
  journal={IBM Developer},
  year={2024},
  url={https://github.com/yourusername/beeai-context-engineering}
}

Support

• 📖 Read the full article
• 🐛 Report issues
• 💬 Start a discussion
• 📧 Contact: shailesh.padekar@in.ibm.com

Roadmap

• Part 2: Vector database integration with real embeddings
• Part 3: Full observability and monitoring pipeline
• Part 4: Multi-agent orchestration patterns
• Part 5: Production deployment with Docker/Kubernetes

---

Note: This code is for educational purposes. Production deployment requires appropriate error handling, security controls, secrets management, and infrastructure configuration.