# Dasein

**Universal memory for agentic AI.** Attach a brain to any LangChain/LangGraph agent in a single line.

Dasein learns from your agent's execution history and automatically injects learned rules to improve performance, reduce costs, and increase reliability across runs.

## Features

✨ **Zero-friction integration** - Wrap any LangChain or LangGraph agent in one line  
🧠 **Automatic learning** - Agents learn from successes and failures  
📊 **Performance tracking** - Built-in token usage, timing, and success metrics  
🔄 **Retry logic** - Intelligent retry with learned optimizations  
🔍 **Execution traces** - Detailed step-by-step visibility into agent behavior  
☁️ **Cloud-powered** - Distributed rule synthesis and storage

## Installation

```bash
pip install dasein-core
```

Or install from source:

```bash
git clone https://github.com/nickswami/dasein-core.git
cd dasein-core
pip install -e .
```

## 📓 Try It Now in Colab

<div align="center">

**🚀 Zero setup required! Try all three examples in your browser:**

<a href="https://colab.research.google.com/github/nickswami/dasein-core/blob/main/examples/dasein_examples.ipynb" target="_blank">
  <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab" style="height: 60px;"/>
</a>

**Three complete examples with automatic learning:**

🗄️ **SQL Agent** • 🌐 **Browser Agent** • 🔍 **Deep Research**

*30-50% token reduction • Optimized navigation • 20-40% multi-agent savings*

</div>

---

## Quick Start

### Basic Usage

```python
from dasein import cognate
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain.agents import create_sql_agent
from langchain_community.agent_toolkits import SQLDatabaseToolkit

# Create your agent as usual
llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash")
toolkit = SQLDatabaseToolkit(db=your_database, llm=llm)
agent = create_sql_agent(llm=llm, toolkit=toolkit, agent_type="tool-calling")

# Wrap with Dasein - that's it!
agent = cognate(agent)

# Use exactly like the original
result = agent.run("Show me the top 5 customers by revenue")
```

### With Performance Tracking

```python
from dasein import cognate

# Enable automatic retry and performance comparison
agent = cognate(
    your_agent,
    retry=2,  # Run twice to learn and improve
    performance_tracking=True  # Show before/after metrics
)

result = agent.run("your query")
# 🎯 Dasein automatically shows improvement metrics
```

### Advanced: Custom Optimization Weights

```python
from dasein import cognate

# Customize what Dasein optimizes for
agent = cognate(
    your_agent,
    weights={
        "w1": 2.0,  # Heavily favor successful rules
        "w2": 0.5,  # Less emphasis on turn count
        "w3": 1.0,  # Standard uncertainty penalty
        "w4": 3.0,  # Heavily optimize for token efficiency
        "w5": 0.1   # Minimal time emphasis
    }
)
```

## Architecture

Dasein uses a **cloud-first architecture** for rule learning and synthesis:

```
┌─────────────────┐
│  Your Agent     │
│  (LangChain/    │
│   LangGraph)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Dasein Wrapper  │  ◄── cognate()
│ - Trace Capture │
│ - Rule Injection│
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌────────┐
│Pre-Run │ │Post-Run│
│Service │ │Service │
│        │ │        │
│Recalls │ │Learns  │
│Rules   │ │Rules   │
└────────┘ └────────┘
```

### How It Works

1. **Pre-Run**: Dasein queries cloud services for relevant learned rules based on the task
2. **Execution**: Rules are injected into the agent's prompts/tools at optimal injection points
3. **Trace Capture**: Every LLM call, tool invocation, and decision is captured
4. **Post-Run**: Traces are sent to cloud services for rule synthesis and learning
5. **Next Run**: Improved rules are automatically available

## API Reference

### Core Functions

#### `cognate(agent, weights=None, verbose=False, retry=0, performance_tracking=False, rule_trace=False)`

Wrap any LangChain/LangGraph agent with Dasein's learning capabilities.

**Parameters:**
- `agent` - LangChain or LangGraph agent instance
- `weights` (dict) - Custom optimization weights for rule selection (w1-w5)
- `verbose` (bool) - Enable detailed debug logging
- `retry` (int) - Number of retries with learning (0 = single run, 2 = run twice with improvement)
- `performance_tracking` (bool) - Show before/after performance metrics
- `rule_trace` (bool) - Show detailed rule application trace

**Returns:** Wrapped agent with identical interface to the original

#### `print_trace()`

Display the execution trace of the last agent run.

#### `get_trace()`

Retrieve the execution trace as a list of dictionaries.

**Returns:** `List[Dict]` - Trace steps with timestamps, tokens, and decisions

#### `clear_trace()`

Clear the current execution trace.

#### `inject_hint(hint: str)`

Manually inject a hint/rule for the next agent run.

**Parameters:**
- `hint` (str) - The hint text to inject

#### `reset_brain()`

Clear all local state and event storage.

## Supported Frameworks

- ✅ LangChain Agents (all agent types)
- ✅ LangGraph Agents (CompiledStateGraph)
- ✅ Custom agents implementing standard interfaces

## Examples

See the `examples/` directory for complete examples:

- **SQL Agent** - Learn query patterns for a Chinook database
- **Browser Agent** - Learn web scraping strategies
- **Research Agent** - Multi-agent research coordination

## Verbose Mode

For debugging, enable verbose logging:

```python
agent = cognate(your_agent, verbose=True)
```

This shows detailed information about:
- Rule retrieval from cloud services
- Rule injection points and content
- Trace capture steps
- Post-run learning triggers

## Requirements

- Python 3.8+
- LangChain 0.1.0+
- LangChain Community 0.1.0+
- LangChain Google GenAI 0.0.6+

See `pyproject.toml` for complete dependency list.

## Configuration

Dasein uses cloud services for rule synthesis and storage. Configure service endpoints via environment variables:

```bash
export DASEIN_PRE_RUN_URL="https://your-pre-run-service.com"
export DASEIN_POST_RUN_URL="https://your-post-run-service.com"
```

Contact the Dasein team for cloud service access.

## Performance

Dasein is designed for minimal overhead:
- **Pre-run**: ~100-200ms for rule retrieval
- **Runtime**: <1% overhead for trace capture
- **Post-run**: Async - doesn't block your code

The benefits far outweigh the costs:
- 🎯 30-50% token reduction on repeated tasks
- 🎯 Fewer failed runs through learned error handling
- 🎯 Faster execution with optimized tool usage

## Contributing

We welcome contributions! Please see `CONTRIBUTING.md` for guidelines.

## License

MIT License - see `LICENSE` file for details.

## Troubleshooting

### Common Issues in Colab/Jupyter

**Q: I see timeout warnings for `dasein-pre-run` and `dasein-post-run` services**

A: These warnings can appear on first connection while the cloud services wake up (cold start). The services are **fully public** and will work after a brief initialization period. Your agent will continue running and learning will activate automatically once the services respond.

**Q: I see dependency conflict warnings**

A: These are safe to ignore in Colab. The package will work correctly despite version mismatches with Colab's pre-installed packages.

---

## Support

- 🐛 Issues: [GitHub Issues](https://github.com/nickswami/dasein-core/issues)

## Citation

If you use Dasein in your research, please cite:

```bibtex
@software{dasein2025,
  title={Dasein: Universal Memory for Agentic AI},
  author={Dasein Team},
  year={2025},
  url={https://github.com/nickswami/dasein-core}
}
```

---

**Built with ❤️ for the agentic AI community**

