1# BDI Framework Integration Patterns
2 
3Integration patterns for connecting BDI ontology with executable agent frameworks.
4 
5## SEMAS Rule Translation
6 
7Map BDI ontology constructs to SEMAS production rules.
8 
9### Ontology-to-Rule Mapping
10 
11| BDI Construct | SEMAS Element | Example |
12|---------------|---------------|---------|
13| Belief | HEAD fact | `belief(agent_a, store_open)` |
14| Supporting beliefs | CONDITIONALS | `[CONDITIONALS: time(weekday)]` |
15| Desire generation | TAIL action | `generate_desire(agent, goal)` |
16| Intention commitment | TAIL action | `commit_intention(agent, goal)` |
17| Plan specification | TAIL action | `create_plan(agent, plan_id)` |
18 
19### Rule Templates
20 
21**Belief triggers desire formation:**
22```prolog
23[HEAD: belief(Agent, Fact)] / 
24[CONDITIONALS: context_condition(Agent, Context)] » 
25[TAIL: generate_desire(Agent, DesiredState)].
26```
27 
28**Desire triggers intention commitment:**
29```prolog
30[HEAD: desire(Agent, Goal)] / 
31[CONDITIONALS: belief(Agent, SupportingFact1), 
32               belief(Agent, SupportingFact2)] » 
33[TAIL: commit_intention(Agent, Goal)].
34```
35 
36**Intention triggers planning:**
37```prolog
38[HEAD: intention(Agent, Goal)] / 
39[CONDITIONALS: goal(GoalSpec)] » 
40[TAIL: create_plan(Agent, PlanId)].
41```
42 
43**Plan triggers execution:**
44```prolog
45[HEAD: plan(Agent, PlanId)] / 
46[CONDITIONALS: ready_to_execute(Agent)] » 
47[TAIL: execute_plan(Agent, PlanId)].
48```
49 
50### Complete SEMAS Example
51 
52```prolog
53% ============================================================
54% GROCERY SHOPPING SCENARIO
55% ============================================================
56 
57% Phase 1: Belief formation from world state
58[HEAD: perceive(agent_a, store_open)] / 
59[CONDITIONALS: time(weekday_afternoon)] » 
60[TAIL: add_belief(agent_a, store_open)].
61 
62% Phase 2: Desire generation from belief
63[HEAD: belief(agent_a, store_open)] / 
64[CONDITIONALS: belief(agent_a, needs_groceries)] » 
65[TAIL: generate_desire(agent_a, buy_groceries)].
66 
67% Phase 3: Intention commitment from desire
68[HEAD: desire(agent_a, buy_groceries)] / 
69[CONDITIONALS: belief(agent_a, has_shopping_list), 
70               belief(agent_a, store_open),
71               belief(agent_a, has_transportation)] » 
72[TAIL: commit_intention(agent_a, buy_groceries)].
73 
74% Phase 4: Plan creation from intention
75[HEAD: intention(agent_a, buy_groceries)] / 
76[CONDITIONALS: goal(complete_shopping)] » 
77[TAIL: create_plan(agent_a, shopping_plan)].
78 
79% Phase 5: Plan execution
80[HEAD: plan(agent_a, shopping_plan)] / 
81[CONDITIONALS: preconditions_met(shopping_plan)] » 
82[TAIL: execute_task(agent_a, drive_to_store),
83       execute_task(agent_a, select_items),
84       execute_task(agent_a, checkout),
85       execute_task(agent_a, return_home)].
86 
87% Phase 6: World state update
88[HEAD: task_complete(agent_a, checkout)] / 
89[CONDITIONALS: items_purchased(agent_a)] » 
90[TAIL: update_world_state(has_groceries),
91       remove_desire(agent_a, buy_groceries),
92       remove_intention(agent_a, buy_groceries)].
93```
94 
95### Python Translation Layer
96 
97```python
98from rdflib import Graph, Namespace, RDF
99 
100BDI = Namespace("https://w3id.org/fossr/ontology/bdi/")
101 
102def ontology_to_semas_rules(bdi_graph: Graph) -> list[str]:
103    """
104    Translate BDI ontology instances to SEMAS production rules.
105    """
106    rules = []
107    
108    # Extract belief-desire-intention chains
109    for intention in bdi_graph.subjects(RDF.type, BDI.Intention):
110        # Get supporting beliefs
111        supporting_beliefs = list(bdi_graph.objects(intention, BDI.isSupportedBy))
112        
113        # Get fulfilled desire
114        fulfilled_desires = list(bdi_graph.objects(intention, BDI.fulfils))
115        
116        # Get specified plan
117        specified_plans = list(bdi_graph.objects(intention, BDI.specifies))
118        
119        if fulfilled_desires and supporting_beliefs:
120            desire = fulfilled_desires[0]
121            beliefs_str = ", ".join([format_belief(b, bdi_graph) for b in supporting_beliefs])
122            
123            rule = (
124                f"[HEAD: {format_desire(desire, bdi_graph)}] / "
125                f"[CONDITIONALS: {beliefs_str}] » "
126                f"[TAIL: commit_intention({format_intention(intention, bdi_graph)})]"
127            )
128            rules.append(rule)
129        
130        if specified_plans:
131            plan = specified_plans[0]
132            rule = (
133                f"[HEAD: {format_intention(intention, bdi_graph)}] / "
134                f"[CONDITIONALS: ready_to_plan] » "
135                f"[TAIL: create_plan({format_plan(plan, bdi_graph)})]"
136            )
137            rules.append(rule)
138    
139    return rules
140 
141def format_belief(belief_uri, graph):
142    label = graph.value(belief_uri, RDFS.label)
143    return f"belief({label or belief_uri.split('/')[-1]})"
144 
145def format_desire(desire_uri, graph):
146    label = graph.value(desire_uri, RDFS.label)
147    return f"desire({label or desire_uri.split('/')[-1]})"
148 
149def format_intention(intention_uri, graph):
150    label = graph.value(intention_uri, RDFS.label)
151    return f"intention({label or intention_uri.split('/')[-1]})"
152 
153def format_plan(plan_uri, graph):
154    label = graph.value(plan_uri, RDFS.label)
155    return f"plan({label or plan_uri.split('/')[-1]})"
156```
157 
158## Logic Augmented Generation (LAG)
159 
160Augment LLM outputs with BDI ontological constraints.
161 
162### LAG Pipeline Architecture
163 
164```
165┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
166│   User Query    │────▶│  Ontology       │────▶│  Augmented      │
167│                 │     │  Injection      │     │  Prompt         │
168└─────────────────┘     └─────────────────┘     └─────────────────┘
169                                                        │
170                                                        ▼
171┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
172│  Validated      │◀────│  Ontology       │◀────│  LLM Response   │
173│  RDF Triples    │     │  Validation     │     │  (Triples)      │
174└─────────────────┘     └─────────────────┘     └─────────────────┘
175```
176 
177### LAG Implementation
178 
179```python
180from rdflib import Graph, Namespace
181from rdflib.plugins.parsers.notation3 import BadSyntax
182 
183BDI = Namespace("https://w3id.org/fossr/ontology/bdi/")
184 
185class BDILogicAugmentedGenerator:
186    def __init__(self, ontology_path: str, llm_client):
187        self.ontology = Graph()
188        self.ontology.parse(ontology_path, format='turtle')
189        self.llm = llm_client
190    
191    def generate_mental_states(self, context: str) -> Graph:
192        """
193        Generate BDI mental states from context using LAG.
194        """
195        # Phase 1: Inject ontology into prompt
196        ontology_turtle = self.ontology.serialize(format='turtle')
197        augmented_prompt = self._build_augmented_prompt(context, ontology_turtle)
198        
199        # Phase 2: Generate with LLM
200        response = self.llm.generate(augmented_prompt)
201        
202        # Phase 3: Extract and validate triples
203        triples = self._extract_triples(response)
204        validated = self._validate_against_ontology(triples)
205        
206        if not validated['is_consistent']:
207            # Retry with feedback
208            return self._retry_with_feedback(context, validated['errors'])
209        
210        return validated['graph']
211    
212    def _build_augmented_prompt(self, context: str, ontology: str) -> str:
213        return f"""
214You are a BDI mental state modeler. Given the following context, generate 
215RDF triples representing the agent's beliefs, desires, and intentions.
216 
217## BDI Ontology (use these classes and properties):
218{ontology}
219 
220## Context to Model:
221{context}
222 
223## Instructions:
2241. Identify world states from the context
2252. Generate beliefs that refer to those world states
2263. Generate desires motivated by those beliefs
2274. Generate intentions that fulfill desires and are supported by beliefs
2285. Include justifications for each mental state
2296. Include temporal validity intervals
230 
231Output valid Turtle RDF triples only.
232"""
233    
234    def _extract_triples(self, response: str) -> str:
235        """Extract Turtle content from LLM response."""
236        # Find turtle block in response
237        if "```turtle" in response:
238            start = response.find("```turtle") + 9
239            end = response.find("```", start)
240            return response[start:end].strip()
241        return response
242    
243    def _validate_against_ontology(self, triples: str) -> dict:
244        """Validate generated triples against BDI ontology."""
245        result = {'is_consistent': True, 'errors': [], 'graph': None}
246        
247        try:
248            generated = Graph()
249            generated.parse(data=triples, format='turtle')
250            result['graph'] = generated
251            
252            # Validate constraints
253            errors = []
254            
255            # Check: Every intention must fulfill a desire
256            for intention in generated.subjects(RDF.type, BDI.Intention):
257                if not list(generated.objects(intention, BDI.fulfils)):
258                    errors.append(f"Intention {intention} does not fulfill any desire")
259            
260            # Check: Every belief should reference a world state
261            for belief in generated.subjects(RDF.type, BDI.Belief):
262                if not list(generated.objects(belief, BDI.refersTo)):
263                    errors.append(f"Belief {belief} does not reference a world state")
264            
265            # Check: Desires should be motivated by beliefs
266            for desire in generated.subjects(RDF.type, BDI.Desire):
267                if not list(generated.objects(desire, BDI.isMotivatedBy)):
268                    errors.append(f"Desire {desire} has no motivating belief")
269            
270            if errors:
271                result['is_consistent'] = False
272                result['errors'] = errors
273                
274        except BadSyntax as e:
275            result['is_consistent'] = False
276            result['errors'] = [f"Invalid Turtle syntax: {e}"]
277        
278        return result
279    
280    def _retry_with_feedback(self, context: str, errors: list) -> Graph:
281        """Retry generation with error feedback."""
282        feedback_prompt = f"""
283Previous generation had errors:
284{chr(10).join(errors)}
285 
286Please regenerate the mental states fixing these issues.
287 
288Context: {context}
289"""
290        response = self.llm.generate(feedback_prompt)
291        triples = self._extract_triples(response)
292        result = self._validate_against_ontology(triples)
293        
294        if result['is_consistent']:
295            return result['graph']
296        else:
297            raise ValueError(f"Failed to generate valid mental states: {result['errors']}")
298```
299 
300### Inconsistency Detection Example
301 
302```python
303def detect_location_inconsistency(graph: Graph) -> list[str]:
304    """
305    Detect inconsistencies where agent cannot be in two places.
306    """
307    inconsistencies = []
308    
309    # Query for location beliefs
310    query = """
311    PREFIX bdi: <https://w3id.org/fossr/ontology/bdi/>
312    
313    SELECT ?agent ?belief1 ?belief2 ?loc1 ?loc2 WHERE {
314        ?agent bdi:hasBelief ?belief1 , ?belief2 .
315        ?belief1 bdi:refersTo ?ws1 .
316        ?belief2 bdi:refersTo ?ws2 .
317        ?ws1 bdi:hasLocation ?loc1 .
318        ?ws2 bdi:hasLocation ?loc2 .
319        FILTER(?belief1 != ?belief2 && ?loc1 != ?loc2)
320        
321        # Check temporal overlap
322        ?belief1 bdi:hasValidity ?interval1 .
323        ?belief2 bdi:hasValidity ?interval2 .
324        ?interval1 bdi:hasStartTime ?start1 ; bdi:hasEndTime ?end1 .
325        ?interval2 bdi:hasStartTime ?start2 ; bdi:hasEndTime ?end2 .
326        FILTER(?start1 < ?end2 && ?start2 < ?end1)
327    }
328    """
329    
330    for row in graph.query(query):
331        inconsistencies.append(
332            f"Agent {row.agent} has conflicting location beliefs: "
333            f"{row.loc1} and {row.loc2} at overlapping times"
334        )
335    
336    return inconsistencies
337```
338 
339## JADE/JADEX Integration
340 
341Map BDI ontology to JADE/JADEX agent platform structures.
342 
343### JADE Agent Structure
344 
345```java
346public class BDIAgent extends Agent {
347    // Mental state storage (maps to ontology individuals)
348    private Set<Belief> beliefs = new HashSet<>();
349    private Set<Desire> desires = new HashSet<>();
350    private Set<Intention> intentions = new HashSet<>();
351    
352    // Ontology-backed mental state management
353    private Graph mentalStateGraph;
354    
355    public void addBelief(Belief belief) {
356        beliefs.add(belief);
357        
358        // Add to RDF graph
359        Resource beliefResource = mentalStateGraph.createResource(belief.getUri());
360        beliefResource.addProperty(RDF.type, BDI.Belief);
361        beliefResource.addProperty(BDI.refersTo, belief.getWorldState().getUri());
362        beliefResource.addProperty(BDI.hasValidity, createInterval(belief.getValidity()));
363        
364        // Trigger desire formation
365        triggerDesireProcess(belief);
366    }
367    
368    public void commitIntention(Intention intention) {
369        intentions.add(intention);
370        
371        Resource intentionResource = mentalStateGraph.createResource(intention.getUri());
372        intentionResource.addProperty(RDF.type, BDI.Intention);
373        intentionResource.addProperty(BDI.fulfils, intention.getDesire().getUri());
374        
375        for (Belief support : intention.getSupportingBeliefs()) {
376            intentionResource.addProperty(BDI.isSupportedBy, support.getUri());
377        }
378        
379        // Trigger planning
380        triggerPlanning(intention);
381    }
382    
383    // Export mental states as RDF
384    public String exportMentalStates() {
385        return mentalStateGraph.serialize(Format.TURTLE);
386    }
387    
388    // Import mental states from RDF
389    public void importMentalStates(String turtle) {
390        Graph imported = new Graph();
391        imported.parse(turtle, Format.TURTLE);
392        
393        // Reconstruct Java objects from RDF
394        for (Resource belief : imported.listSubjectsWithProperty(RDF.type, BDI.Belief)) {
395            Belief b = reconstructBelief(belief);
396            beliefs.add(b);
397        }
398        // ... similar for desires and intentions
399    }
400}
401```
402 
403### JADEX Goal Mapping
404 
405```java
406// Map BDI ontology goals to JADEX goals
407@Goal
408public class OntologyBackedGoal {
409    @GoalParameter
410    protected String goalUri;
411    
412    @GoalParameter
413    protected Graph ontologyGraph;
414    
415    public OntologyBackedGoal(Resource goalResource, Graph graph) {
416        this.goalUri = goalResource.getURI();
417        this.ontologyGraph = graph;
418    }
419    
420    @GoalTargetCondition
421    public boolean isAchieved() {
422        // Query ontology for goal achievement
423        String query = """
424            PREFIX bdi: <https://w3id.org/fossr/ontology/bdi/>
425            ASK {
426                ?execution bdi:addresses <%s> ;
427                           bdi:bringsAbout ?worldState .
428            }
429            """.formatted(goalUri);
430        
431        return ontologyGraph.ask(query);
432    }
433    
434    @GoalDropCondition
435    public boolean shouldDrop() {
436        // Check if supporting beliefs are invalidated
437        String query = """
438            PREFIX bdi: <https://w3id.org/fossr/ontology/bdi/>
439            ASK {
440                ?intention bdi:specifies ?plan .
441                ?plan bdi:addresses <%s> .
442                ?intention bdi:isSupportedBy ?belief .
443                ?belief bdi:hasValidity ?interval .
444                ?interval bdi:hasEndTime ?end .
445                FILTER(?end < NOW())
446            }
447            """.formatted(goalUri);
448        
449        return ontologyGraph.ask(query);
450    }
451}
452```
453 
454## RDF Triple Store Integration
455 
456### Triple Store Configuration
457 
458```python
459from rdflib import Graph
460from rdflib.plugins.stores.sparqlstore import SPARQLUpdateStore
461 
462class BDIMentalStateStore:
463    def __init__(self, endpoint: str):
464        self.store = SPARQLUpdateStore()
465        self.store.open((endpoint + "/query", endpoint + "/update"))
466        self.graph = Graph(store=self.store, identifier="http://example.org/bdi")
467    
468    def add_belief(self, agent_uri: str, belief_data: dict):
469        """Add belief to triple store."""
470        belief_uri = f"{agent_uri}/belief/{belief_data['id']}"
471        
472        self.graph.add((URIRef(belief_uri), RDF.type, BDI.Belief))
473        self.graph.add((URIRef(belief_uri), RDFS.label, Literal(belief_data['label'])))
474        self.graph.add((URIRef(belief_uri), BDI.refersTo, URIRef(belief_data['world_state'])))
475        self.graph.add((URIRef(agent_uri), BDI.hasMentalState, URIRef(belief_uri)))
476        
477        # Add temporal validity
478        interval_uri = f"{belief_uri}/validity"
479        self.graph.add((URIRef(belief_uri), BDI.hasValidity, URIRef(interval_uri)))
480        self.graph.add((URIRef(interval_uri), BDI.hasStartTime, 
481                        Literal(belief_data['start_time'], datatype=XSD.dateTime)))
482        self.graph.add((URIRef(interval_uri), BDI.hasEndTime,
483                        Literal(belief_data['end_time'], datatype=XSD.dateTime)))
484    
485    def get_active_beliefs(self, agent_uri: str, at_time: datetime) -> list:
486        """Query beliefs active at specific time."""
487        query = """
488        PREFIX bdi: <https://w3id.org/fossr/ontology/bdi/>
489        PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
490        
491        SELECT ?belief ?label WHERE {
492            <%s> bdi:hasMentalState ?belief .
493            ?belief a bdi:Belief ;
494                    rdfs:label ?label ;
495                    bdi:hasValidity ?interval .
496            ?interval bdi:hasStartTime ?start ;
497                      bdi:hasEndTime ?end .
498            FILTER(?start <= "%s"^^xsd:dateTime && ?end >= "%s"^^xsd:dateTime)
499        }
500        """ % (agent_uri, at_time.isoformat(), at_time.isoformat())
501        
502        return list(self.graph.query(query))
503    
504    def get_cognitive_chain(self, intention_uri: str) -> dict:
505        """Trace complete cognitive chain for an intention."""
506        query = """
507        PREFIX bdi: <https://w3id.org/fossr/ontology/bdi/>
508        
509        SELECT ?intention ?desire ?belief ?worldState ?plan WHERE {
510            <%s> a bdi:Intention ;
511                 bdi:fulfils ?desire ;
512                 bdi:isSupportedBy ?belief .
513            OPTIONAL { <%s> bdi:specifies ?plan }
514            ?desire bdi:isMotivatedBy ?belief .
515            ?belief bdi:refersTo ?worldState .
516        }
517        """ % (intention_uri, intention_uri)
518        
519        results = list(self.graph.query(query))
520        if results:
521            row = results[0]
522            return {
523                'intention': str(row.intention),
524                'desire': str(row.desire),
525                'belief': str(row.belief),
526                'world_state': str(row.worldState),
527                'plan': str(row.plan) if row.plan else None
528            }
529        return None
530```
531 
532## FIPA ACL Integration
533 
534Map BDI mental states to FIPA Agent Communication Language.
535 
536```python
537from fipa_acl import ACLMessage, Performative
538 
539class BDICommunicator:
540    def __init__(self, agent_id: str, mental_state_store: BDIMentalStateStore):
541        self.agent_id = agent_id
542        self.store = mental_state_store
543    
544    def share_belief(self, belief_uri: str, receiver: str) -> ACLMessage:
545        """Create INFORM message to share belief."""
546        belief_triples = self.store.get_belief_as_turtle(belief_uri)
547        
548        message = ACLMessage()
549        message.performative = Performative.INFORM
550        message.sender = self.agent_id
551        message.receiver = receiver
552        message.content = belief_triples
553        message.ontology = "https://w3id.org/fossr/ontology/bdi/"
554        message.language = "turtle"
555        
556        return message
557    
558    def request_belief_confirmation(self, belief_uri: str, receiver: str) -> ACLMessage:
559        """Create QUERY-IF message to confirm shared belief."""
560        message = ACLMessage()
561        message.performative = Performative.QUERY_IF
562        message.sender = self.agent_id
563        message.receiver = receiver
564        message.content = f"ASK {{ <{belief_uri}> a bdi:Belief }}"
565        message.language = "sparql"
566        
567        return message
568    
569    def propose_intention(self, intention_uri: str, receiver: str) -> ACLMessage:
570        """Create PROPOSE message for coordinated intention."""
571        intention_triples = self.store.get_intention_as_turtle(intention_uri)
572        
573        message = ACLMessage()
574        message.performative = Performative.PROPOSE
575        message.sender = self.agent_id
576        message.receiver = receiver
577        message.content = intention_triples
578        message.ontology = "https://w3id.org/fossr/ontology/bdi/"
579        
580        return message
581```
582 
583