https://github.com/shalinianandaphd/neuron
Neuron is a composable agent framework inspired by cognitive neuroscience. It enables you to build, orchestrate, and monitor intelligent multi-agent systems using a modular circuit-based architecture.
https://github.com/shalinianandaphd/neuron
agent-based-modeling ai-agents automation cognitive-computing distributed-ai machine-learning multi-agent-system neural-networks reinforcement-learning robotics
Last synced: 9 months ago
JSON representation
Neuron is a composable agent framework inspired by cognitive neuroscience. It enables you to build, orchestrate, and monitor intelligent multi-agent systems using a modular circuit-based architecture.
- Host: GitHub
- URL: https://github.com/shalinianandaphd/neuron
- Owner: ShaliniAnandaPhD
- License: other
- Created: 2025-03-22T22:17:49.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-20T18:43:02.000Z (9 months ago)
- Last Synced: 2025-07-20T20:32:36.569Z (9 months ago)
- Topics: agent-based-modeling, ai-agents, automation, cognitive-computing, distributed-ai, machine-learning, multi-agent-system, neural-networks, reinforcement-learning, robotics
- Language: Python
- Homepage: https://www.notion.so/shalini-ananda-phd/Neuron-A-Journey-Through-Modular-Intelligence-1f7c18ea2aa18081a07ce75683eec80b
- Size: 22.5 MB
- Stars: 14
- Watchers: 2
- Forks: 1
- Open Issues: 50
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Open Source Attribution Notice
Using open source software without proper attribution or in violation of license terms is not only ethically problematic but may also constitute a legal violation ⚠️ . I believe in supporting the open source community that makes projects like this possible.
If you're using code or tools from this repository or GitHub, please ensure you maintain all attribution notices and comply with all applicable licenses.
The license above is a *modified MIT LICENSE* for the purpose of this project 👆
📄 For full legal terms and enforcement policy, read the [Neuron Legal Notice & Enforcement Terms](https://www.notion.so/shalini-ananda-phd/LEGAL-NOTICE-ENFORCEMENT-TERMS-NEURON-FRAMEWORK-200c18ea2aa1803aa07ddbb41cd9080d).
-----------------------------------
# Neuron: A Brain-Inspired AI Framework for Complex Reasoning
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/sanity_check.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/run_ambiguity_audit.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/verify_microservices_layout.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/ambiguity_visual_asset_check.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/verify-agent-names.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/ambiguity_ci_setup_check.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/ambiguity_input_validation.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/ip-protection-plus.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/ip-monitoring.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/lego-agent-builder.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/lego-marketplace.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/check-tone-phrase.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/performance-auto-swap.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/neuron_log_writer.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/finetune.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/agent_factory.yml)
[](https://github.com/ShaliniAnandaPhD/Neuron/actions/workflows/check_message_intent_keyword.yml)
> **Neuron is a composable AI framework that thinks in circuits, not chains.**
Traditional AI orchestration tools collapse under real-world complexity—contradictions, sarcasm, conflicting goals, or mixed data formats. Neuron addresses these breakdown zones through **modular reasoning circuits** inspired by how the brain actually processes information.
```
┌─────────────────────────────────────────┐
│ NEURON ARCHITECTURE │
└─────────────────────────────────────────┘
│
┌──────────────┬─────────┼─────────┬──────────────┐
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌──────────┐ ┌─────────┐ ┌───────┐ ┌─────────┐ ┌─────────┐
│Perception│ │ Memory │ │Synaptic│ │Reasoning│ │Expression│
│ Modules │ │ System │ │ Bus │ │ Modules │ │ Modules │
│ │ │ │ │ │ │ │ │ │
│• Language│◄►│• Episodic│◄►│ Coord │◄►│• Logic │◄►│• Response│
│• Vision │ │• Semantic│ │ Layer │ │• Planning│ │• Adapt │
│• Audio │ │• Working │ │ │ │• Temporal│ │• Format │
│• Multi.. │ │• Context │ │ │ │• Causal │ │• Tone │
└──────────┘ └─────────┘ └───────┘ └─────────┘ └─────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Self-Monitoring │ │ Adaptability │
│ │ │ │
│• Error Detection │ │• Dynamic Routing │
│• Uncertainty │ │• Context Shift │
│• Explanation │ │• Resource Alloc │
└──────────────────┘ └──────────────────┘
```
## 🧠 Why Neuron?
**Cognitive Multi-Agent Architecture for Complex AI Systems**
Neuron is a research framework exploring cognitive architectures through modular multi-agent coordination. Built on neuroscience-inspired principles, it provides sophisticated agent coordination patterns and memory systems for developing resilient AI applications.
🔬 **Current Status: Advanced Research Platform** - Production-ready architecture with agent behavior modeling. Suitable for research, prototyping, and foundational development of cognitive AI systems.
Neuron excels in scenarios traditional AI struggles with:
- **🔄 Resilient Processing**: Handles ambiguous inputs, contradictory information, and incomplete data without system failure
- **🧠 Persistent Memory**: Maintains context across extended interactions for longitudinal reasoning
- **⚡ Selective Activation**: Dynamically combines only needed capabilities rather than running every component
- **🔀 Parallel Coordination**: Processes multiple tasks simultaneously while maintaining consistency
- **👁️ Complete Observability**: Every decision is traceable with full reasoning paths and evidence trails
### Where Neuron Shines
| Use Case | Traditional AI | Neuron Agent Approach |
|----------|----------------|----------------------|
| Contradictory Customer Requests | Fails or picks one instruction | **Agent consensus** detects contradiction, requests clarification |
| Multi-Session Medical History | Loses context between visits | **Memory agents** maintain episodic history with temporal reasoning |
| Emergency Response Triage | Static rule-based priority | **Coordination agents** provide dynamic multi-modal assessment |
| Regulatory Compliance | Rigid rule checking | **Reasoning agents** perform contextual interpretation with conflict resolution |
### 🧠 Neuron: A Journey Through Modular Intelligence
[Main Documentation](https://www.notion.so/shalini-ananda-phd/Neuron-A-Journey-Through-Modular-Intelligence-1f7c18ea2aa18081a07ce75683eec80b)
## 📚 Documentation & Tutorials
### 🤖 Neuron as an Agent Orchestrator: How It Chooses, Evaluates, and Integrates Agents
[View Documentation](https://www.notion.so/shalini-ananda-phd/Neuron-as-an-Agent-Orchestrator-How-It-Chooses-Evaluates-and-Integrates-Agents-1fbc18ea2aa1801ea227e59480caedf1)
### 📋 Neuron Evaluation Notebook
[Access Evaluation Framework](https://www.notion.so/shalini-ananda-phd/Neuron-Evaluation-Notebook-1cec18ea2aa18002b7acf9c1791ca8ea)
### 📚 Neuron Framework Tutorial Series: Cognitive Architecture for Modular AI
[Access Tutorials](https://www.notion.so/shalini-ananda-phd/Neuron-Framework-Tutorial-Series-Cognitive-Architecture-for-Modular-AI-1fec18ea2aa180b5b1dff554f651bb01)
### 🏗️ Building the Neuron Sandbox: Behind the Scenes of Modular AI Architecture
[Development Insights](https://www.notion.so/shalini-ananda-phd/Building-the-Neuron-Sandbox-Behind-the-Scenes-of-Modular-AI-Architecture-1fac18ea2aa180b89cf3ec456d6845a3)
## 🌍 Applications & Case Studies
### 🌐 Real World Use Cases
[Explore Use Cases](https://www.notion.so/shalini-ananda-phd/Real-World-Use-Cases-1ffc18ea2aa180059a1cc44637326c84)
### 🎯 NeuroCircuit: The Multi-Agent System I Built for Reliable AI Focus
[System Overview](https://www.notion.so/shalini-ananda-phd/NeuroCircuit-The-Multi-Agent-System-I-Built-for-Reliable-AI-Focus-208c18ea2aa18048845ada542b565abd)
### 🏥 Neuron Fine-Tuning for Healthcare
[Healthcare Applications](https://www.notion.so/shalini-ananda-phd/Neuron-Fine-Tuning-for-Healthcare-20bc18ea2aa1801eafa0fba178e08143)
## 🚀 Quick Start
### Installation
```bash
git clone https://github.com/ShaliniAnandaPhD/Neuron.git
cd Neuron
pip install -e .
```
### Your First Agent Circuit
```python
from neuron import initialize, create_agent, CircuitDefinition
from neuron.agents import ReflexAgent, DeliberativeAgent
# Initialize the agent framework
core = initialize()
# Define a cognitive reasoning circuit with agent coordination
circuit_def = CircuitDefinition.create(
name="CustomerSupportCircuit",
description="Handles complex customer issues with agent memory coordination",
agents={
"intake": {
"type": "ReflexAgent",
"role": "INPUT",
"capabilities": ["sentiment_analysis", "intent_detection"]
},
"reasoner": {
"type": "DeliberativeAgent",
"role": "PROCESSOR",
"capabilities": ["contradiction_detection", "memory_retrieval"]
},
"responder": {
"type": "ReflexAgent",
"role": "OUTPUT",
"capabilities": ["response_generation", "tone_adaptation"]
}
},
connections=[
{"source": "intake", "target": "reasoner", "type": "direct"},
{"source": "reasoner", "target": "responder", "type": "conditional"}
]
)
# Deploy and test agent coordination
circuit_id = core.circuit_designer.create_circuit(circuit_def)
core.circuit_designer.deploy_circuit(circuit_id)
# Process a complex request through agent network
response = core.circuit_designer.send_input(circuit_id, {
"customer_id": "12345",
"message": "I love this product but it's completely broken and I want a refund but also keep it",
"context": "third_complaint_this_month"
})
print(response) # Agent network detects contradiction and requests clarification
```
## 🏗️ Core Agent Architecture
### Specialized Agent Types
Neuron provides specialized agents for different cognitive functions:
```python
# Quick response pattern-matching agents
reflex_agent = create_agent(ReflexAgent,
name="IntakeAgent",
capabilities=["sentiment_analysis", "classification"])
# Deep reasoning and analysis agents
deliberative_agent = create_agent(DeliberativeAgent,
name="ReasoningAgent",
capabilities=["logical_inference", "contradiction_detection"])
# Learning and adaptation agents
learning_agent = create_agent(LearningAgent,
name="AdaptiveAgent",
capabilities=["pattern_recognition", "strategy_evolution"])
# Coordination and orchestration agents
coordinator_agent = create_agent(CoordinatorAgent,
name="OrchestratorAgent",
capabilities=["resource_allocation", "priority_management"])
```
### Multi-Layered Memory Systems
Neuron implements sophisticated memory architecture for agent coordination:
```python
# Access different memory types for agents
memory_manager = core.memory_manager
# Immediate context and active processing
working_memory = memory_manager.get_memory_system(MemoryType.WORKING)
# Sequential events and interaction history
episodic_memory = memory_manager.get_memory_system(MemoryType.EPISODIC)
# Conceptual knowledge and relationships
semantic_memory = memory_manager.get_memory_system(MemoryType.SEMANTIC)
# Learned processes and strategies
procedural_memory = memory_manager.get_memory_system(MemoryType.PROCEDURAL)
# Store and retrieve contextual information across agents
episodic_memory.store({
"event": "customer_complaint",
"timestamp": "2024-01-15T10:30:00Z",
"context": {"customer_id": "12345", "sentiment": "frustrated"},
"resolution": "product_replacement_offered"
})
# Retrieve relevant past interactions for agent reasoning
relevant_history = episodic_memory.query(
context={"customer_id": "12345"},
timeframe="last_30_days"
)
```
### SynapticBus Agent Communication
Agents communicate through a brain-inspired message passing system:
```python
from neuron import Message
# Create and send messages between agents
message = Message.create(
sender="intake_agent",
recipients=["reasoning_agent", "memory_agent"],
content={
"type": "customer_issue",
"data": {"sentiment": "mixed", "intent": "unclear"},
"confidence": 0.75,
"requires_reasoning": True
},
metadata={
"priority": "high",
"timeout": 30,
"fallback_required": True
}
)
await core.synaptic_bus.send(message)
```
### Dynamic Agent Circuit Composition
Build adaptive processing pipelines that reconfigure agent routing based on context:
```python
# Create circuits that adapt agent routing to complexity
adaptive_circuit = CircuitDefinition.create(
name="AdaptiveReasoningCircuit",
routing_strategy="confidence_based",
fallback_strategy="graceful_degradation",
agents={
"simple_classifier": {
"type": "ReflexAgent",
"activation_threshold": 0.8, # High confidence required
"capabilities": ["quick_classification"]
},
"deep_reasoner": {
"type": "DeliberativeAgent",
"activation_threshold": 0.3, # Handles uncertain cases
"capabilities": ["complex_reasoning", "uncertainty_quantification"]
},
"contradiction_resolver": {
"type": "DeliberativeAgent",
"activation_condition": "contradiction_detected",
"capabilities": ["conflict_resolution", "clarification_generation"]
}
},
decision_rules=[
{
"condition": "confidence > 0.8",
"route": "simple_classifier"
},
{
"condition": "contradiction_detected == True",
"route": "contradiction_resolver"
},
{
"default": True,
"route": "deep_reasoner"
}
]
)
```
## 🎯 Real-World Agent Applications
### Healthcare: Modular Compliance & Clinical Decision Support
```python
# HIPAA-aware healthcare agent circuit
healthcare_circuit = CircuitDefinition.create(
name="ClinicalDecisionSupport",
compliance_modules=["hipaa_monitor", "clinical_guidelines"],
agents={
"triage": {"type": "ReflexAgent", "capabilities": ["symptom_analysis"]},
"risk_scorer": {"type": "DeliberativeAgent", "capabilities": ["risk_assessment"]},
"compliance_checker": {"type": "ValidatorAgent", "capabilities": ["hipaa_validation"]}
}
)
```
### Emergency Response: Multi-Modal Crisis Processing
```python
# Crisis response with multi-format input handling agents
crisis_circuit = CircuitDefinition.create(
name="EmergencyResponseSystem",
input_types=["text", "voice", "social_media", "sensor_data"],
agents={
"input_processor": {"capabilities": ["multi_modal_parsing"]},
"priority_ranker": {"capabilities": ["urgency_assessment", "resource_allocation"]},
"response_coordinator": {"capabilities": ["dispatch_optimization", "status_tracking"]}
}
)
```
### Customer Support: Multi-Session Relationship Management
```python
# Customer retention with cross-session memory agents
support_circuit = CircuitDefinition.create(
name="CustomerRetentionIntelligence",
memory_integration=True,
agents={
"relationship_analyzer": {"capabilities": ["sentiment_tracking", "churn_prediction"]},
"issue_resolver": {"capabilities": ["problem_solving", "escalation_management"]},
"retention_strategist": {"capabilities": ["intervention_planning", "satisfaction_optimization"]}
}
)
```
## 🔧 Advanced Agent Features
### Self-Monitoring and Error Detection
Neuron includes built-in agent reliability mechanisms:
```python
# Configure agent monitoring and fallback behavior
monitoring_config = {
"hallucination_detection": True,
"uncertainty_quantification": True,
"contradiction_detection": True,
"automatic_fallback": True,
"explanation_generation": True
}
# Monitor agent health in real-time
health_status = core.neuro_monitor.get_health_status()
performance_metrics = core.neuro_monitor.get_metrics("circuit.*")
```
### Temporal Reasoning and Causal Analysis
```python
# Enable temporal reasoning capabilities in agents
temporal_agent = create_agent(DeliberativeAgent,
capabilities=[
"timeline_reconstruction",
"causal_chain_analysis",
"dependency_tracking",
"scenario_projection"
]
)
# Analyze complex temporal scenarios
timeline_analysis = temporal_agent.process({
"events": mixed_chronological_data,
"analysis_type": "causal_dependencies",
"projection_horizon": "30_days"
})
```
### Agent Explainability Dashboard
Every agent decision in Neuron is fully traceable:
```python
# Access detailed agent reasoning paths
explanation = core.explainability.get_decision_trace(
circuit_id="customer_support_001",
request_id="req_12345"
)
print(explanation.reasoning_tree) # Step-by-step agent logic
print(explanation.confidence_scores) # Certainty at each agent step
print(explanation.alternative_paths) # Other agent options considered
print(explanation.evidence_sources) # Supporting information used by agents
```
## 🔌 Agent Microservices & Extensions
Neuron's modular architecture supports plug-and-play agent microservices:
### Available Agent Microservices
- **🔍 Ambiguity Resolution Agent**: Detects and handles unclear inputs
- **⚖️ Contradiction Detection Agent**: Identifies logical conflicts
- **🧠 Memory Optimization Agent**: Manages contextual memory efficiently
- **📊 Performance Analytics Agent**: Tracks system-wide agent metrics
- **🔧 Dynamic Reconfiguration Agent**: Adapts agent circuits in real-time
### Custom Agent Development
```python
from neuron.microservices import BaseAgent
class CustomAnalysisAgent(BaseAgent):
"""Custom domain-specific analysis agent"""
def __init__(self):
super().__init__(name="domain_analyzer")
async def process(self, input_data):
# Your custom agent logic here
analysis_result = self.analyze_domain_specifics(input_data)
return {
"analysis": analysis_result,
"confidence": self.calculate_confidence(analysis_result),
"recommendations": self.generate_recommendations(analysis_result)
}
# Register and deploy your agent
core.agent_manager.register(CustomAnalysisAgent())
```
## 🧪 Agent Testing and Evaluation
### Built-in Agent Testing Framework
```python
# Test agent circuit resilience
test_results = core.testing.run_stress_tests(
circuit_id="customer_support_001",
test_scenarios=[
"contradictory_inputs",
"incomplete_information",
"component_failures",
"high_load_conditions"
]
)
# Evaluate agent memory persistence
memory_tests = core.testing.evaluate_memory_systems(
retention_periods=["1_hour", "1_day", "1_week"],
decay_patterns=["importance_weighted", "recency_based"]
)
```
### Agent Performance Benchmarking
```python
# Compare agent performance against other frameworks
benchmark_results = core.benchmarking.compare_against([
"langchain_equivalent",
"direct_api_calls",
"custom_pipeline"
], test_cases="real_world_scenarios")
```
## 🌟 Why Choose Neuron?
## 🌟 Why Choose Neuron's Agent Architecture?
### **vs. LangChain**
- **Memory**: Persistent multi-layered **agent memory** vs. token-level context
- **Reasoning**: Parallel **multi-agent coordination** vs. sequential chains
- **Observability**: Full **agent decision traces** vs. execution logs only
- **Adaptability**: Dynamic **agent reconfiguration** vs. manual flow updates
### **vs. Direct API Calls**
- **State Management**: Rich **agent memory systems** vs. stateless calls
- **Error Handling**: Graceful **agent degradation** vs. hard failures
- **Coordination**: **Multi-agent orchestration** vs. single-shot responses
- **Explainability**: Complete **agent reasoning traces** vs. black box outputs
### **vs. AutoGen/CrewAI**
- **Brain-Inspired Design**: Neuroscience-based **agent principles** vs. generic multi-agent
- **Memory Architecture**: Sophisticated **agent persistence** vs. simple conversation history
- **Fault Tolerance**: Component-level **agent resilience** vs. system-wide failures
- **Observability**: Deep **agent introspection** vs. basic logging
## 🚀 Getting Started
1. **[Install Neuron](#installation)** and run the quick start example
2. **[Go through the Tutorials in Google Colab](Tutorials/)** to understand the architecture
3. **[Read the Evaluation Notebook](https://shalini-ananda-phd.notion.site/NEURON-EVALUATION-NOTEBOOK-1cec18ea2aa18002b7acf9c1791ca8ea)** to understand capabilities
4. **[Join the Community](https://github.com/ShaliniAnandaPhD/Neuron/discussions)** for support and contributions
## 🤝 Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
References
1. Anderson, J. R., & Lebiere, C. (2003). The Newell Test for a theory of cognition. Behavioral and Brain Sciences, 26(5), 587-640.
Relevance: Foundational work on cognitive architectures that inspired Neuron's modular agent design and memory integration patterns.
2. Hassabis, D., Kumaran, D., Summerfield, C., & Botvinick, M. (2017). Neuroscience-inspired artificial intelligence. Neuron, 95(2), 245-258.
Relevance: Provides the theoretical framework for translating neuroscience principles into AI architectures, particularly memory systems and hierarchical processing.
3. Stone, P., & Veloso, M. (2000). Multiagent systems: A survey from a machine learning perspective. Autonomous Robots, 8(3), 345-383.
Relevance: Establishes foundational principles for multi-agent coordination and communication protocols that inform Neuron's SynapticBus architecture.
4. Tulving, E. (2002). Episodic memory: From mind to brain. Annual Review of Psychology, 53(1), 1-25.
Relevance: Seminal work on episodic memory systems that directly influenced Neuron's multi-layered memory architecture and temporal reasoning capabilities.
5. Gal, Y., & Ghahramani, Z. (2016). Dropout as a Bayesian approximation: Representing model uncertainty in deep learning. International Conference on Machine Learning, 1050-1059.
Relevance: Theoretical foundation for uncertainty quantification methods used in Neuron's confidence-based routing and self-monitoring systems.
6. Cox, M. T. (2005). Metacognition in computation: A selected research review. Artificial Intelligence, 169(2), 104-141.
Relevance: Provides the conceptual framework for self-monitoring and introspective capabilities that enable Neuron's error detection and adaptive behavior mechanisms.
This software was created and is maintained by Shalini Ananda (GitHub: @ShaliniAnandaPhD).
Any use of this framework without attribution, or any commercial repackaging, is a violation of the license terms and may constitute copyright infringement.
Please review the LICENSE.md for conditions. Reach out via GitHub Sponsors for partnership or licensing discussions.