gns3-server/gns3server/agent/gns3_copilot/deprecated/README.md

Deprecated Context Manager

This directory contains the advanced context management implementation that has been replaced with a simplified version.

What's in Here

• context_manager.py (~650 lines)
  • Accurate token counting using tiktoken
  • Tool definition token estimation
  • Custom message trimming with AIMessage + ToolMessage pairing
  • Detailed logging and diagnostics

Why Was It Moved?

The advanced implementation was over-engineered for the current use case:

Feature	Complexity	Necessity	Current Status
Template injection	Low	✅ Essential	Kept (in new version)
Token counting (tiktoken)	High	❓ Optional	Moved here
Message trimming	Medium	❓ Optional	Simplified (LangChain native)
Tool token estimation	High	❓ Optional	Moved here
AIMessage/ToolMessage pairing	High	✅ Important	Moved here
3 strategies (conservative/balanced/aggressive)	Low	✅ Useful	Kept (in new version)

When to Use This Implementation

Use the deprecated version if:

1. You need accurate token counting

   • Your model has strict token limits
   • You need to know exact token usage
   • You're working with cost-sensitive applications

2. You have many tools

   • Tool definitions consume significant tokens (500-1500 per tool)
   • You need to account for tool tokens in context limit

3. You need AIMessage + ToolMessage pairing

   • Your LLM requires tool calls and results to stay together
   • You've encountered errors from orphaned ToolMessages

4. You need detailed diagnostics

   • Debugging context limit issues
   • Optimizing token usage
   • Fine-tuning context strategy

Use the current simplified version if:

1. ✅ You just need topology injection
2. ✅ Your model has large context (128K+ tokens)
3. ✅ Conversations are typically short (<50 turns)
4. ✅ You don't need exact token counts

How to Restore the Advanced Version

If you find you need the advanced features:

# 1. Remove current simplified version
rm gns3server/agent/gns3_copilot/agent/context_manager.py

# 2. Restore from deprecated
cp gns3server/agent/gns3_copilot/deprecated/context_manager.py \
   gns3server/agent/gns3_copilot/agent/context_manager.py

Key Differences

Simplified Version (Current)

# ~200 lines
- Uses LangChain's native trim_messages
- Simple token estimation (char count / 4)
- Template injection for topology
- 3 strategies: conservative/balanced/aggressive

Advanced Version (Deprecated)

# ~650 lines
- Custom trimming with AIMessage/ToolMessage pairing
- Accurate tiktoken-based token counting
- Tool definition token estimation
- Detailed logging with token breakdown
- Template injection for topology
- 3 strategies: conservative/balanced/aggressive

Performance Comparison

Metric	Simplified	Advanced
Code size	~200 lines	~650 lines
Token accuracy	~80% (estimation)	~95%+ (tiktoken)
Trimming safety	Good	Excellent
Execution speed	Fast	Slower (tiktoken overhead)
Maintenance	Low	High

Future Considerations

If the simplified version proves insufficient:

1. Consider adding tiktoken back (but keep architecture simple)
2. Use LangChain's more advanced trim_messages features
3. Add optional tool token estimation
4. Consider a hybrid approach: simple by default, advanced when needed

---

Moved: 2025-03-05 Reason: Simplification for current use case Status: Available for future use if needed